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": {
        "accountName": "John Smith",
        "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": {
        "accountName": "John Smith",
        "bsb": "064000",
        "number": "XXXXXX78"
    },
    "metadata": {
        "bankName": "Commonwealth Bank of Australia"
    },
    "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), an account number, and an account name submitted as separate fields.

accountName must match the payer name recorded by the financial institution. To support successful processing, provide the name exactly as held by the bank.

Field	Format	Example
accountName	32 chars	John Smith
bsb	6 digits	064000
number	6-9 digits	12345678

{
    "bankAccount": {
        "accountName": "John Smith",
        "bsb": "064000",
        "number": "12345678"
    }
}

New Zealand

New Zealand bank accounts require an account number and an account name submitted as separate fields.

accountName must match the payer name recorded by the financial institution. To support successful processing, provide the name exactly as held by the bank.

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": {
        "accountName": "John Smith",
        "number": "0100011234567123"
    }
}

{
    "bankAccount": {
        "accountName": "John Smith",
        "number": "01-0001-1234567-123"
    }
}

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

{
    "bankAccount": {
        "accountName": "John Smith",
        "number": "01-0001-XXXXX67-123"
    }
}

Example Request (NZ):

{
    "reference": "INV-2026-001",
    "bankAccount": {
        "accountName": "John Smith",
        "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": {
        "accountName": "John Smith",
        "number": "01-0001-XXXXX67-123"
    },
    "metadata": {
        "bankName": "ANZ Bank New Zealand"
    },
    "result": {
        "status": "ok"
    }
}