Direct Debit Payments

Overview

Direct debit lets you collect payments from your customer’s Australian bank account. It’s cheaper than credit cards but operates on a slower schedule; payments are submitted to the bank overnight and results come back over the following 1–3 business days.

This guide shows the most common workflow for integrating direct debit.

📘

New here? Make sure you’ve read API Core Concepts first and have your test credentials ready from Test and Live Mode.

Always include pinch-version: 2020.1 in your API requests.

Workflow Summary

1. Get an access token
2. Create a Payer with bank account details (DDR authorisation is part of this step)
3. Schedule a payment
4. Handle the result via webhooks (recommended) or event polling

Detailed Steps

1. Get an access token

See Application Authentication for the full details. In short:

POST https://auth.getpinch.com.au/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_APP_ID&client_secret=YOUR_SECRET_KEY

Include the token in every subsequent request:

Authorization: Bearer {token}
pinch-version: 2020.1

2. Create a Payer

Every payment in Pinch must be associated with a Payer (the customer you’re collecting from).

You can create a Payer with their bank account details in a single call using a CaptureJS bank account token:

POST https://api.getpinch.com.au/test/payers
Authorization: Bearer {token}
pinch-version: 2020.1
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "mobile": "0400000000",
  "bankAccountToken": "{bank_account_token}"
}

Save the id from the response (format: pyr_XXXXXXXX). See Create or Update Payer for all available fields.

📘

When you create a Payer with a bank account, Pinch automatically creates and authorises the Direct Debit Request (DDR) Agreement as part of this call. The payer receives a confirmation email with a PDF copy of the DDR. No separate authorisation step is needed.

3. Schedule a payment

Direct debit payments are processed overnight on business days. You can schedule for today or any future date.

POST https://api.getpinch.com.au/test/payments
Authorization: Bearer {token}
pinch-version: 2020.1
Content-Type: application/json

{
  "payerId": "pyr_XXXXXXXX",
  "amount": 1000,
  "description": "Invoice #123",
  "transactionDate": "2026-08-01"
}

Save the payment id (format: pmt_XXXXXXXX) from the response. See Create or Update Payment.

📘

Amounts are always in cents. 1000 = $10.00.

4. Handle payment outcomes

⚠️

The initial API response is not your payment result.

When you create a direct debit payment, Pinch returns a pmt_XXXXXXXX ID and a status of pending. This only means the payment has been accepted for processing; it does not mean the money has been collected.

Direct debit operates on the Australian BECS (Bulk Electronic Clearing System). Payments are submitted to the banking network overnight and the actual result (whether the debit succeeded or was dishonoured by the bank) comes back 1–3 business days later via a bank results file. Until that file arrives, the payment will remain in a pending state.

Recommended: Use webhooks. Set up a webhook to receive payment events pushed to your server in real time. See Webhooks.

Alternative: Poll the events endpoint. Use List all events and check for:

• bank-results: this is the real result. It contains the bank's response for payments processed that day. Check each payment's status:
  • approved: the bank confirmed the debit succeeded
  • dishonoured: the bank rejected the payment (e.g. insufficient funds, account closed). The dishonour.type field tells you why.
• transfer: confirms funds have been settled to your bank account

Use Get Event to retrieve the full payload, then match payment IDs against your records. If a payment is dishonoured, it's up to you to decide whether to retry; create a new payment using the same payerId.

📘

See Dishonour Codes for a full list of failure reasons and how to handle them.

What to do next

• Webhooks: set up real-time event delivery instead of polling
• Payment Statuses: understand the full payment lifecycle
• Dishonour Codes: handle failed payments correctly
• Plans and Subscriptions: automate recurring direct debit billing
• CaptureJS Tokenisation: full bank account tokenisation reference