Events are generated every time something happens behind the scenes in Pinch these allow API integrators hooks into the system when these events are triggered.

Consuming Events

To consume these events there are multiple options:

Webhooks - Webhooks can be created either through the Webhooks API or via the Pinch Developer Portal
Events API - There are 2 API endpoints for events that can be used to poll for events as required, List All Events Endpoint and Get Event Endpoint.
Zapier - Our Zapier integration exposes triggers for these events that can be used to trigger Zaps
n8n - Our n8n Integration exposes a trigger node that allows consumption of these events into n8n workflows

Event types

This is a list of all the types of events we currently send. We may add more at any time, so in developing and maintaining your code, you should not assume that only these types exist.

`bank-results`

Occurs whenever a bank account transaction returns (as these take time to process) and could result in a dishonour status. If you are taking bank account transactions you will need to listen for this event otherwise you may miss failed payments.

data.payments is a list of BankResultPayment

bank-results Example Payload

{
  "Id": "evt_def456",
  "Type": "bank-results",
  "EventDate": "2026-04-10T08:00:00.000Z",
  "Metadata": {
    "SuccessCount": 45,
    "SuccessAmount": 125000,
    "DishonourCount": 3,
    "DishonourAmount": 8500
  },
  "Data": {
    "Payments": [
      {
        "Id": "pmt_001",
        "AttemptId": "att_001a",
        "Amount": 5000,
        "Description": "Membership fee",
        "SourceType": "direct-debit",
        "TransactionDate": "2026-04-09T00:00:00.000Z",
        "Status": "approved",
        "EstimatedTransferDate": "2026-04-11T00:00:00.000Z",
        "Payer": {
          "Id": "pyr_abc001",
          "FirstName": "Alice",
          "LastName": "Johnson",
          "Email": "[email protected]"
        }
      },
      {
        "Id": "pmt_002",
        "AttemptId": "att_002a",
        "Amount": 3500,
        "Description": "Service payment",
        "SourceType": "direct-debit",
        "TransactionDate": "2026-04-09T00:00:00.000Z",
        "Status": "dishonoured",
        "EstimatedTransferDate": "2026-04-11T00:00:00.000Z",
        "Payer": {
          "Id": "pyr_abc002",
          "FirstName": "Bob",
          "LastName": "Williams",
          "Email": "[email protected]"
        },
        "Dishonour": {
          "Type": "insufficient-funds",
          "Reason": "Refer to Drawer"
        }
      }
    ]
  }
}

`scheduled-process`

Occurs whenever scheduled Payments are processed (daily on business days).

data.payments is a list of PaymentWithPayer

scheduled-process Example Payload

{
  "Id": "evt_efg123",
  "Type": "scheduled-process",
  "EventDate": "2026-04-10T02:00:00.000Z",
  "Metadata": {},
  "Data": {
    "Payments": [
      {
        "Id": "pmt_sched001",
        "Amount": 7500,
        "TransactionDate": "2026-04-10T02:00:00.000Z",
        "Description": "Scheduled recurring payment",
        "Status": "submitted",
        "EstimatedTransferDate": "2026-04-12T00:00:00.000Z",
        "Payer": {
          "Id": "pyr_recur01",
          "FirstName": "Lisa",
          "LastName": "Anderson",
          "Email": "[email protected]"
        },
        "Subscription": {
          "Id": "sub_monthly01",
          "PlanId": "pln_standard",
          "PlanName": "Standard Monthly"
        }
      }
    ]
  }
}

`transfer`

Occurs whenever a transfer is created to settle funds to a Merchant.

data.transfer is a Transfer object

scheduled-process Example Payload

{
  "Id": "evt_bcd890",
  "Type": "transfer",
  "EventDate": "2026-04-10T16:00:00.000Z",
  "Metadata": {
    "TransferAmount": 285000
  },
  "Data": {
    "Transfer": {
      "Id": "trf_trans789",
      "Amount": 285000,
      "Currency": "AUD",
      "AccountName": "ABC Company Pty Ltd",
      "AccountNumber": "12345678",
      "Bsb": "063-000",
      "Status": "submitted",
      "Type": "merchant-settlement",
      "Reference": "Settlement 2026-04-10",
      "TransferDate": "2026-04-11",
      "TaxRate": 10,
      "IsGrossBilled": false,
      "StatementReference": "STMT-20260410"
    }
  }
}

`realtime-payment`

Occurs whenever a realtime payment is executed.

data.payment is a Payment object

realtime-payment Example Payload

{
  "Id": "evt_hij456",
  "Type": "realtime-payment",
  "EventDate": "2026-04-10T17:00:00.000Z",
  "Metadata": {},
  "Data": {
    "Payment": {
      "Id": "pmt_realtime01",
      "Amount": 25000,
      "Currency": "AUD",
      "TransactionDate": "2026-04-10T17:00:00.000Z",
      "Description": "One-time payment",
      "Status": "approved",
      "SourceType": "credit-card",
      "EstimatedTransferDate": "2026-04-11",
      "Payer": {
        "Id": "pyr_onetime01",
        "FirstName": "Chris",
        "LastName": "Martin",
        "Email": "[email protected]"
      }
    }
  }
}

`payment-created`

Occurs whenever a Payment is created in Pinch. This could be done through the Save Payment endpoint or when a Subscription creates its payments.

data.payment is a Payment object

payment-created Example Payload

{
  "Id": "evt_abc123",
  "Type": "payment-created",
  "EventDate": "2026-04-10T05:30:00.000Z",
  "Metadata": {
    "Status": "approved",
    "Amount": 15000
  },
  "Data": {
    "Payment": {
      "Id": "pmt_xyz789",
      "Amount": 15000,
      "Currency": "AUD",
      "Description": "Monthly subscription payment",
      "TransactionDate": "2026-04-10T05:30:00.000Z",
      "Status": "approved",
      "SourceType": "direct-debit",
      "EstimatedTransferDate": "2026-04-12",
      "Payer": {
        "Id": "pyr_123abc",
        "FirstName": "John",
        "LastName": "Smith",
        "Email": "[email protected]",
        "Mobile": "+61412345678"
      },
      "Subscription": {
        "Id": "sub_456def",
        "PlanId": "pln_789ghi",
        "PlanName": "Premium Monthly Plan"
      },
      "Metadata": "{\"customerRef\":\"CUST-001\"}"
    }
  }
}

`payer-created`

Occurs whenever a new Payer record is created.

data.payer is a Payer object

payer-created Example Payload

{
  "Id": "evt_pqr678",
  "Type": "payer-created",
  "EventDate": "2026-04-10T12:00:00.000Z",
  "Metadata": {
    "PayerName": "David Taylor"
  },
  "Data": {
    "Payer": {
      "Id": "pyr_david01",
      "FirstName": "David",
      "LastName": "Taylor",
      "Email": "[email protected]",
      "Mobile": "+61411223344",
      "CompanyName": "Taylor Enterprises Pty Ltd",
      "AddressLine1": "123 Main Street",
      "AddressLine2": "Suite 5",
      "Suburb": "Melbourne",
      "State": "VIC",
      "Postcode": "3000",
      "Country": "AU",
      "Metadata": "{\"externalId\":\"EXT-12345\"}"
    }
  }
}

`payer-updated`

Occurs whenever a Payer record is updated.

data.payer is a Payer object

payer-updated Example Payload

{
  "Id": "evt_stu901",
  "Type": "payer-updated",
  "EventDate": "2026-04-10T13:15:00.000Z",
  "Metadata": {
    "PayerName": "Emily Davis"
  },
  "Data": {
    "Payer": {
      "Id": "pyr_emily01",
      "FirstName": "Emily",
      "LastName": "Davis",
      "Email": "[email protected]",
      "Mobile": "+61422334455",
      "AddressLine1": "456 New Address",
      "Suburb": "Sydney",
      "State": "NSW",
      "Postcode": "2000",
      "Country": "AU",
      "Metadata": "{\"updatedFields\":[\"email\",\"mobile\",\"address\"]}"
    }
  }
}

`refund-created`

Occurs whenever a Refund is created.

data.refund is a Refund object

refund-created Example Payload

{
  "Id": "evt_vwx234",
  "Type": "refund-created",
  "EventDate": "2026-04-10T14:00:00.000Z",
  "Metadata": {
    "Status": "pending",
    "Amount": 5000
  },
  "Data": {
    "Refund": {
      "Id": "rfd_ref123",
      "Amount": 5000,
      "Currency": "AUD",
      "RefundFeeCharged": 0,
      "RequestedDate": "2026-04-10T14:00:00.000Z",
      "Status": "pending",
      "ReasonForRefund": "Customer request",
      "IsGross": false,
      "Payment": {
        "Id": "pmt_original789",
        "Amount": 10000,
        "Description": "Original payment"
      }
    }
  }
}

`refund-updated`

Occurs whenever a Refund is updated (such as when the refund status gets updated through its processing).

data.refund is a Refund object

refund-updated Example Payload

{
  "Id": "evt_yza567",
  "Type": "refund-updated",
  "EventDate": "2026-04-10T15:30:00.000Z",
  "Metadata": {
    "Status": "completed",
    "Amount": 5000
  },
  "Data": {
    "Refund": {
      "Id": "rfd_ref123",
      "Amount": 5000,
      "Currency": "AUD",
      "RefundFeeCharged": 0,
      "RequestedDate": "2026-04-10T14:00:00.000Z",
      "CompletedDate": "2026-04-10T15:30:00.000Z",
      "Status": "completed",
      "ReasonForRefund": "Customer request",
      "IsGross": false,
      "TransferId": "trf_transfer456"
    }
  }
}

`compliance-updated`

Occurs whenever a Merchant record is updated that will result in a compliance check (such as updating a Merchant's bank account or when a Merchant uploads a document for verification).

data.complianceSubmission is a Compliance object

compliance-updated Example Payload

{
  "Id": "evt_klm789",
  "Type": "compliance-updated",
  "EventDate": "2026-04-10T18:00:00.000Z",
  "Metadata": {
    "Status": "approved",
    "MerchantStatus": "active",
    "SubmissionDateUtc": "2026-04-10T18:00:00.000Z"
  },
  "Data": {
    "ComplianceSubmission": {
      "Id": "cmp_sub123",
      "SubmissionStatus": "approved",
      "MerchantStatus": "active",
      "SubmissionDate": "2026-04-10T18:00:00.000Z",
      "ReviewedBy": "Compliance Team",
      "Notes": "All documentation verified"
    }
  }
}

`dispute-created`

Occurs whenever a Dispute is created.

data.dispute is a Dispute object

dispute-created Example Payload

{
  "Id": "evt_nop012",
  "Type": "dispute-created",
  "EventDate": "2026-04-10T19:00:00.000Z",
  "Metadata": {
    "Status": "under-review",
    "Outcome": "pending"
  },
  "Data": {
    "Dispute": {
      "Id": "dsp_dispute01",
      "Status": "under-review",
      "Outcome": "pending",
      "Reason": "fraudulent",
      "DisputeDate": "2026-04-10T19:00:00.000Z",
      "Amount": 15000,
      "Currency": "AUD",
      "ReferenceNumber": "DSP-20260410-001",
      "Payment": {
        "Id": "pmt_disputed01",
        "Amount": 15000,
        "TransactionDate": "2026-03-25T00:00:00.000Z"
      }
    }
  }
}

`dispute-updated`

Occurs whenever a Dispute is updated.

data.dispute is a Dispute object

dispute-updated Example Payload

{
  "Id": "evt_qrs345",
  "Type": "dispute-updated",
  "EventDate": "2026-04-10T20:00:00.000Z",
  "Metadata": {
    "Status": "closed",
    "Outcome": "won"
  },
  "Data": {
    "Dispute": {
      "Id": "dsp_dispute01",
      "Status": "closed",
      "Outcome": "won",
      "Reason": "fraudulent",
      "DisputeDate": "2026-04-10T19:00:00.000Z",
      "ResolutionDate": "2026-04-10T20:00:00.000Z",
      "Amount": 15000,
      "Currency": "AUD",
      "ReferenceNumber": "DSP-20260410-001",
      "Notes": "Evidence provided was sufficient"
    }
  }
}

`merchant-updated`

Occurs whenever a Merchant record is updated.

data.merchant is a Merchant object

merchant-updated Example Payload

{
  "Id": "evt_wxy901",
  "Type": "merchant-updated",
  "EventDate": "2026-04-10T22:00:00.000Z",
  "Metadata": {
    "MerchantName": "Updated Business Pty Ltd"
  },
  "Data": {
    "Merchant": {
      "Id": "mrc_merchant01",
      "CompanyName": "Updated Business Pty Ltd",
      "TradingName": "Updated Business",
      "Abn": "12345678901",
      "Email": "[email protected]",
      "Phone": "+61398765432",
      "Status": "active"
    }
  }
}

`subscription-created`

Occurs whenever a Subscription is created for a Payer

data.subscription is a Subscription object

subscription-created Example Payload

{
  "Id": "evt_ghi789",
  "Type": "subscription-created",
  "EventDate": "2026-04-10T09:15:00.000Z",
  "Metadata": {
    "PlanName": "Gold Membership",
    "PayerName": "Jane Doe"
  },
  "Data": {
    "Subscription": {
      "Id": "sub_sub123",
      "PlanId": "pln_gold01",
      "PlanName": "Gold Membership",
      "StartDate": "2026-04-15",
      "Status": "active",
      "TotalAmount": 120000,
      "Payer": {
        "Id": "pyr_jane01",
        "FirstName": "Jane",
        "LastName": "Doe",
        "Email": "[email protected]",
        "Mobile": "+61498765432"
      },
      "RecurringPayment": {
        "Amount": 10000,
        "Frequency": "monthly",
        "FinalPaymentDate": "2026-04-15T00:00:00.000Z"
      },
      "FixedPayments": [],
      "FreePeriods": [],
      "SourceId": "src_bank123",
      "Metadata": "{\"signupChannel\":\"web\"}"
    }
  }
}

`subscription-cancelled`

Occurs whenever a Subscription is cancelled.

data.subscription is a Subscription object

subscription-cancelled Example Payload

{
  "Id": "evt_mno345",
  "Type": "subscription-cancelled",
  "EventDate": "2026-04-10T11:30:00.000Z",
  "Metadata": {
    "PlanName": "Premium Plan",
    "PayerName": "Sarah Wilson"
  },
  "Data": {
    "Subscription": {
      "Id": "sub_canc789",
      "PlanId": "pln_premium",
      "PlanName": "Premium Plan",
      "StartDate": "2026-01-01",
      "Status": "cancelled",
      "Payer": {
        "Id": "pyr_sarah01",
        "FirstName": "Sarah",
        "LastName": "Wilson",
        "Email": "[email protected]"
      },
      "Metadata": "{\"cancellationReason\":\"Customer request\"}"
    }
  }
}

`subscription-complete`

Occurs whenever a Subscription is run to completion.

data.subscription is a Subscription object

subscription-complete Example Payload

{
  "Id": "evt_jkl012",
  "Type": "subscription-complete",
  "EventDate": "2026-04-10T10:00:00.000Z",
  "Metadata": {
    "PlanName": "12 Month Membership",
    "PayerName": "Michael Brown"
  },
  "Data": {
    "Subscription": {
      "Id": "sub_comp456",
      "PlanId": "pln_12month",
      "PlanName": "12 Month Membership",
      "StartDate": "2025-04-10",
      "Status": "complete",
      "TotalAmount": 120000,
      "Payer": {
        "Id": "pyr_mike01",
        "FirstName": "Michael",
        "LastName": "Brown",
        "Email": "[email protected]"
      },
      "Metadata": "{\"completedOn\":\"2026-04-10\"}"
    }
  }
}