BPAY Payin Workflow
Australia only
This guide is for platforms operating in Australia.
Overview
This integration guide will run you through how to use BPAY to directly fund a user’s digital wallet with Zai.
Provide BPAY deposit details to your customers, once they provide funds to the BPAY account, Zai will send a webhook for each customer’s wallet account receiving funds. At this point, you will implement business logic that moves these funds into their digital wallet.
Getting Started
Before you can run your BPAY workflow there are a few setup steps that need to be completed so that all of the pieces are available.
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.
API steps
- Check if a user already exists in Zai.
GET /users/:id
- Create user in Zai if it doesn’t exist in step 1.
POST /users
- Update user in Zai if it does exist in step 1.
PATCH /users/:id
- Get the digital wallet account ID for the user.
GET /users/:id/wallet_accounts
- Get the BPAY details for the user.
GET /wallet_accounts/:id/bpay_details
- (Once off) Set up Callback (webhook) on the transactions object to be notified of incoming BPAY funds.
POST /callbacks
"object_type": "transactions",
- (Once off) Set up Callback (webhook) on the Batch Transactions object to be notified of incoming BPAY funds.
POST /callbacks
"object_type": "batch_transactions",
- (Pre-live only) Fund a user’s digital wallet with BPAY.
PATCH /testing/wallet_accounts/process_bpay
{
"crn": "Customer reference number - reference from wallet",
"amount": 10000 // Amount in cents
}
Once the BPAY payin has happened you will receive the batch_transactions
callback indicating that the BPAY payin is pending.
After settlement of the BPAY payin has occurred (next business day) you will receive the callbacks from step 7 and 8 on the transactions
and/or batch_transactions
object with a status of successful
.
If you are after more information on the BPAY payin you can perform a call on batch_transactions
with passing the batch_transaction id. (see below)
/batch_transactions/dabcfd50-bf5a-0138-7b40-0a58a9feac03
- Create Item (use Type=2) to pay the payin account from the user’s account.
POST /items
- Fund the Item with the user’s digital wallet account.
PATCH /items/:id/make_payment
Funds will be automatically disbursed to your bank account.
Design considerations
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.
User data design
your_customer_id | zai_user_id | zai_bank_account_id | zai_digital_wallet_id | zai_user_bpay_crn |
---|---|---|---|---|
10001001 | 5b8f59b6-32c1-44a3-8f5b-b9e2c77bc265 | fb35b028-76fb-44df-86ac-822dccf1cd7d | dcdfdb78-27e7-485d-90c0-11ffbf950d72 | 1000023456 |
10001002 | efe6f8c1-0a30-484a-b085-9d9d0539dbfc | 4355de7b-18c2-4892-b800-b7bbb6f0a9b3 | 054cd04e-19f1-4938-908b-8e9e5c212f4d | 1000098653 |
Payin data design
your_payin_id | zai_item_id | zai_batch_transaction_id |
---|---|---|
30001001 | 1563db1c-add2-4dcd-ae20-5ad3802bf1c4 | 1ddb9cbb-90a7-41c6-bbbe-05e44f3134f1 |
30001002 | f827dbb5-ba17-4241-a282-14336351faff | 445bbaf3-c9bc-41aa-aec4-c9a99944941d |
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 to:
- Create user in Zai if it doesn’t exist in step 1.
POST /users
- Update user in Zai if it does exist in step 1.
PATCH /users/:id
- Catch the callback when the user’s digital wallet is funded via BPAY.
- Create Item to pay the payin account from the user’s account.
POST /items
- Fund the Item with the user’s digital wallet account.
PATCH /items/:id/make_payment
Updated about 2 months ago