BPAY Payout Workflow

📘

Australia only

This guide is for platforms operating in Australia.

Overview

This integration guide will run you through how to use Zai to pay BPAY bills from your user's main wallet account and, if using the stored value account, from sub-wallet accounts.
To pay, your users you only need their BPAY Biller Code and Customer Reference Number (CRN). Zai will look up and validate these details with BPAY before adding a BPAY account and allowing the payment to go through.

Getting Started

Before you can run your BPAY payout workflow, there are a few steps that need to be completed to get set up so that all of the pieces are available.

Prerequisites
You'll need to capture specific details (BPAY Biller Code and Customer Reference Number) from your users for you to be able to pay a BPAY bill/account. These details will be used to create a BPAY account representing the bill being paid.

The user's wallet account will need to have sufficient funds to perform the BPAY payout to the BPAY biller. You can refer to our Real Time Payins Workflow and BPAY Payins workflow guides on how to top a user's wallet account.

Before you start creating sub-wallets, ensure your platform is approved for use of stored value accounts and enabled for sub-wallets by contacting Zai's Account Management team(mailto:[email protected]). Or you can get in touch with us at [email protected].

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.
• Payout​ is money being paid out of the Zai ecosystem.
• Float user is a User you may create, if required, to temporarily hold the balance of funds (float) you wish to split and transfer to multiple users' wallet accounts before you perform the payouts.
• Callbacks are legacy implementations of webhooks.

API steps

Setup steps
We recommend that you create webhooks (callbacks) 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'd call ​POST /callbacks, more information on callbacks can be ​found here​. Also reference our Webhooks guide and best practices. POST /webhooks

1. (Once off) Set up ​callback​ (webhook) on the Batch Transactions object to be notified of status updates to bill payments.
   POST /callbacks

2. Create a BPAY Account ​for your user account by passing the BPAY Biller Code and Customer Reference Number (CRN) provided on the bill the user needs to pay.
   POST /bpay_accounts

3. Get the ​wallet​ account ID for your float user.
   GET /users/:id/wallet_accounts

4. (Main wallet account) Create a Pay a Bill request on the wallet to pay to your user’s nominated BPAY account (use the BPAY account ID from step 2).
   POST /wallet_accounts/:id/bill_payment
   a. (Sub-wallet account) Create a Pay a Bill request on the sub-wallet to pay your user's nominated BPAY account (use the BPAY account ID from step 2).
   POST /sub_wallets/:id/bill_payment

5. As part of step 4, you'll receive a disbursements object. Please hold on to the id field as you'll need to pass it on to us to progress the bill payment.

6. (Main wallet account) Check the wallet balance of your user to confirm funds have been sent. GET /wallet_accounts/:id
   a. (Sub-wallet account) Check the sub-wallet balance of your user to confirm funds have been sent. GET /sub_wallets/:id

7. (Pre-live only) You can call the PATCH /batches/:id/transaction_states 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.

📘

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.

{
	"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": []
}

8. (Pre-Live only) You can call the same PATCH /batches/:id/transaction_states API from step 7 to move one or more batch_transactions to the final states of processing being either successful state 12000 or invalid_account_details state 12360. 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.

{
	"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": []
}

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.

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 payout workflow in production will be reduced.

This flow assumes that you have a webhook (callback) service running, that your user exists, and that a BPAY account has been added.

1. Create an Item to move money to the user who'll be paying the bill.
   POST /items
2. Fund the Item specifying the user’s wallet.
   PATCH /items/:id/make_payment
3. (Main wallet account) Create a bill_payment request on the wallet to pay to the user’s BPAY biller (use the BPAY account ID from the creation step).
   POST /wallet_accounts/:id/bill_payment
   a. (Sub-wallet account) Create a bill_payment request on the sub-wallet to pay the user's BPAY biller (use the BPAY account ID from the creation step).
   POST /sub_wallets/:id/bill_payment

Failed BPAY Payouts
In the case of a failure relating to the BPAY payout, the batch_transactions object will be transitioned to invalid_account_details and the BPAY payout account used will be switched to inactive active=false.

The account will no longer be usable and you should confirm the BPAY payout account details and create a new BPAY payout account to try the BPAY payout once more.

Additional Details

For a list of BPAY payout error codes, please refer to: Common error messages
For a list of BPAY payout test data, please refer to: Test data
For general FAQs on BPAY please refer to:

• Payout Options