Direct Debit Payin Workflow

📘

Australia only

This guide is for platforms operating in Australia.

Overview

This integration guide will run you through how to do payins via direct debit (ACH / DE / BECS). You will need to capture a user's bank account details into a bank account and then create an item between buyer/payer and seller/payee. Afterwards, you perform a make payment action on that item specifying the bank account of the buyer/payer.

Getting Started

Before you can run your direct debit workflow, there are a few setup steps that need to be completed so that all of the pieces are available.

Prerequisites
You will need to capture specific details from your users for you to be able to perform direct debits.
The setup discussed in this guide makes use of a float to fund your payout.

Terminology used
The following terminology is used throughout this guide:

• Platform​ refers to you as a Zai customer, or your website, application, marketplace etc.
• User​ refers to your customer who has a User record in Zai.
• Item​ is the mechanism for moving funds between users in the API.
• Payin​ is money being paid into the Zai ecosystem from a bank account.
• Payout​ is money being paid out of the Zai ecosystem to a bank account.

API steps

Setup steps
We recommend that you create callbacks (webhooks) on the following objects to receive notifications from us of state and status changes.

• Transactions
• Items
• Users
• Batch Transactions
• Accounts

To create a callback, you would call ​POST /callbacks. More information on callbacks can be ​found here​.

Inbound payments (topping up your float - Pre-live only)
The following steps allow you to add funds to a user’s digital wallet in our Pre-live environment. In the real world, you would send us a payment and we would match it to the wallet. For testing purposes, you can add funds to wallets as needed.

API steps

1. Create a user for your customer (who you want to pay) if they don’t exist already.
   POST /users
2. Update the user for your customer if they already exist (if needed).
   PATCH /users/:id
3. Add a ​bank account​ for your customer (you’ll need the bank account ID in further steps).
   POST /bank_accounts
4. Create a seller ​user​ in Zai.
   POST /users
5. [Create an Item] (https://developer.hellozai.com/reference/createitem) between the buyer and the seller.
   POST /items
6. (Once off) Set up ​Callback​ (webhook) on the ​items​ object to be notified of when the item status changes.
   POST /callbacks

"object_type": "items",

7. (Once off) Set up Callback (webhook) on the ​transactions​ object to be notified of when the transaction state changes
   POST /callbacks

"object_type": "transactions",

8. (Once off) Set up ​Callback (webhook) on the batch_transactions object to be notified of when the transaction state changes
   POST /callbacks

"object_type": "batch_transactions",

9. Call Make Payment on the item and specify the 'bank account_id' (obtained from step 3).
   PATCH /items/:id/make_payment

Once the make_payment API has been called, Zai will attempt to send the direct debit out via its bank. This will result in the following to occur:

10. (Pre-live only) You can call the GET /batch_transactions/export_transactions API which moves all pending batch_transactions into batched state. As a result, this API will return all the batch_transactions that have moved from pending to exported. This will simulate the step of the flow where we batch payments and will result in you receiving a batch_transactions webhook which has the direct debit payment transaction. Please store the id in order to progress it in Pre-live.

📘

Note

When you simulate a payment journey in Pre-live, the response including the transaction id will be cleared after a day. If you need to retrieve this id, you can call the List Transactions API, input a limited number of results depending on how much time has passed, and then find it from that list of transactions.

{
    "transactions": [
        {
            "id": "439970a2-e0a1-418e-aecf-6b519c115c55",
            "batch_id": null,
            "status": "batched",
            "type": "payment",
            "type_method": "direct_debit"
        }
    ]
}

11. (Pre-live only) You can call the following API which moves one or more batch_transactions into bank_processing state 12700. This will simulate the step of the flow where we send payments to our bank and will result in you receiving a batch_transactions webhook
    PATCH /batches/:id/transaction_states

{
	"exported_ids" : ["439970a2-e0a1-418e-aecf-6b519c115c55"],
	"state": 12700
}

{
    "aggregated_jobs_uuid": "c1cbc502-9754-42fd-9731-2330ddd7a41f",
    "msg": "1 jobs have been sent to the queue.",
    "errors": []
}

12. (Pre-live only) You can call the same API from the step above to move one or more batch_transactions to the final states of processing being either successful state 12000 or invalid_account_details state 12360 or failed_direct_debit state 12370. This will simulate the step of the flow where we complete the processing of the payment and will result in you receiving a batch_transactions webhook and an items webhook for completion in case of successful.
    PATCH /batches/:id/transaction_states

{
	"exported_ids" : ["439970a2-e0a1-418e-aecf-6b519c115c55"],
	"state": 12000
}

{
    "aggregated_jobs_uuid": "c1cbc502-9754-42fd-9731-2330ddd7a41f",
    "msg": "1 jobs have been sent to the queue.",
    "errors": []
}

Alternatively, rather than waiting for webhooks, you can check the Callback payload to see that the payout was completed.
GET /callbacks/id:/responses

Design considerations

User data design
When designing how this workflow will interface with your platform, we suggest storing a map of specific object IDs on your side in order to reduce the number of API calls required throughout the API workflow.

Payment descriptors
For direct debit payins descriptors please refer to our Payment Descriptors article.

Workflow summary
Once you’ve run through the API steps, and implemented something like the above in your platform, the sequence of calls to run the payin workflow in production will be reduced. It will exclude any Pre-live steps listed above

Failed Direct Debit Payins
In the case of a failure relating to direct credit payouts, the batch_transactions object will be transitioned to invalid_account_details or failed_direct_debit. In this case you should verify the account details with the user and aim to create a new account with the correct details before reattempting the payment

Additional Details

For a list of error codes please refer to: Common error messages
For a list of statuses, please refer to: Statuses
For FAQs about payouts, please refer to:

• Payout Options
• Payment Processing
• Payment Descriptors