Direct Debit Flow

Direct debit payments require a customer record and a stored bank account. Once the bank account is tokenised as a payment instrument, transactions are submitted and settle asynchronously. The final result is delivered via webhook. It is also available via transaction reports, and queries.

Steps: Create Customer → Add Bank Account → Process Transaction

Step 1: Create a Customer

If you don’t already have a customer record, create one first.

Endpoint: POST /customers

For complete field documentation, see Create a Customer.

Example Request:

{
    "name": "Jane Smith",
    "email": "janesmith@example.com"
}

Response:

{
    "id": "YJaKdxGP6UGn_kk4OCDqUQ",
    "name": "Jane Smith",
    "email": "jXXXXXXXXXX@example.com",
    "reference": "CUST-001",
    "createdDateTime": "2026-05-06T01:24:56Z",
    "updatedDateTime": "2026-05-06T01:24:56Z",
    "count": 0,
    "paymentInstruments": [],
    "result": {
        "status": "ok"
    }
}

Step 2: Add a Bank Account

Add the customer’s bank account as a payment instrument. This tokenises the account details and returns an instrument ID you can reuse for future transactions.

Endpoint: POST /customers/{customerId}/PaymentInstruments

For complete field documentation, see Create a Payment Instrument.

Example Request:

{
    "reference": "INV-2026-001",
    "bankAccount": {
        "bsb": "064000",
        "number": "12345678"
    }
}

Response:

{
    "reference": "FwBZ5ldAj0yOuIk84m0XPA",
    "id": "z2CtwzPuZUqLYqLHPRHPaw",
    "type": "bank_account",
    "createdDateTime": "2026-05-06T01:03:59Z",
    "updatedDateTime": "2026-05-06T01:03:59Z",
    "bankAccount": {
        "bsb": "064001",
        "number": "XXXXXX78"
    },
    "result": {
        "status": "ok"
    }
}

Step 3: Process a Transaction

Submit a direct debit transaction using the customer ID and payment instrument ID. The response status is pending because the bank settles the debit asynchronously.

Endpoint: POST /transactions

For complete field documentation, see Create a Transaction.

Example Request:

{
    "reference": "INV-2026-001",
    "payment": {
        "amount": 5000,
        "instrument": {
            "customer": {
                "id": "YJaKdxGP6UGn_kk4OCDqUQ",
                "paymentInstrumentId": "z2CtwzPuZUqLYqLHPRHPaw"
            }
        }
    }
}

Response:

{
    "id": "FbDnBIDc_US4vbjbG5kX0Q",
    "reference": "INV-2026-001",
    "createdDateTime": "2026-05-06T01:33:05Z",
    "updatedDateTime": "2026-05-06T01:33:05Z",
    "category": {
        "method": "purchase",
        "source": "direct_debit"
    },
    "payment": {
        "amount": 5000,
        "currencyCode": "AUD",
        "instrument": {
            "customer": {
                "id": "YJaKdxGP6UGn_kk4OCDqUQ",
                "paymentInstrumentId": "z2CtwzPuZUqLYqLHPRHPaw"
            }
        }
    },
    "result": {
        "mode": "sandbox",
        "status": "pending"
    }
}

Step 4: Receive the Webhook

When the bank processes and settles the debit, the API sends a webhook with the final result. The result.status will be approved or declined. The result is also available via transaction reports and queries.

Note: Configure your webhook endpoint in the API settings. See Webhooks for more details.

Flow Diagram

sequenceDiagram
    autonumber
    participant Customer
    participant Merchant Server
    participant Single API

    Customer->>Merchant Server: Provide bank account details and authorise debit
    Merchant Server->>Single API: POST /customers
    Single API-->>Merchant Server: Customer ID
    Merchant Server->>Single API: POST /customers/{id}/PaymentInstruments
    Single API-->>Merchant Server: Payment Instrument ID (token)
    Merchant Server->>Single API: POST /transactions (customer ID + instrument ID)
    Single API-->>Merchant Server: status: pending
    Note over Single API: Bank processes debit asynchronously
    Single API-->>Merchant Server: Webhook: approved or declined
    Merchant Server-->>Customer: Display result

Bank Account Formats

Australia

Australian bank accounts require a BSB (Bank State Branch) and an account number submitted as separate fields.

Field	Format	Example
bsb	6 digits	064000
number	6-9 digits	12345678

{
    "bankAccount": {
        "bsb": "064000",
        "number": "12345678"
    }
}

New Zealand

New Zealand bank accounts use a 16-digit number structured as BB-bbbb-AAAAAAA-SSS:

Part	Description	Digits
BB	Bank code	2
bbbb	Branch code	4
AAAAAAA	Account body	7
SSS	Suffix (account type)	2-3

You can submit the number with, or without hyphens:

{
    "bankAccount": {
        "number": "0100011234567123"
    }
}

{
    "bankAccount": {
        "number": "01-0001-1234567-123"
    }
}

The API always returns the account number masked and formatted with hyphens:

{
    "bankAccount": {
        "number": "01-0001-XXXXX67-123"
    }
}

Example Request (NZ):

{
    "reference": "INV-2026-001",
    "bankAccount": {
        "number": "01-0001-1234567-123"
    }
}

NZ Response:

{
    "reference": "FwBZ5ldAj0yOuIk84m0XPA",
    "id": "z2CtwzPuZUqLYqLHPRHPaw",
    "type": "bank_account",
    "createdDateTime": "2026-05-06T01:03:59Z",
    "updatedDateTime": "2026-05-06T01:03:59Z",
    "bankAccount": {
        "number": "01-0001-XXXXX67-123"
    },
    "result": {
        "status": "ok"
    }
}