BPAY Payout Workflow

Overview

This integration guide will run you through how to use Assembly to do BPAY payout from your users wallet accounts to billers.
To pay your users you only need their BPAY Biller Code and Customer Reference Number (CRN). Assembly will look up these details up on BPAY prior to 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 setup steps that need to be completed so that all of the pieces are available.

Prerequisites
You will need to capture specific details (BPAY Biller Code and Customer Reference Number) from your users for you to be able to send funds via the BPAY. These details will need to be used to create a BPAY account representing the biller being paid to.
The user 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

Terminology used
The following terminology is used throughout this guide:

• Platform​ refers to your platform (you, your website, app, marketplace etc.).
• User​ refers to your customer who will have a User record in Assembly.
• Item​ is the mechanism for moving funds between users in the API.
• Payin​ is money being paid into the Assembly ecosystem.
• Payout​ is money being paid out of the Assembly ecosystem to a bank account.
• ASM​ is shorthand for Assembly
• Callback​ is Assembly speak for a Webhook.

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​.

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 Create BPay Account ​for your user account 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 ​digital wallet​ account ID for your Float User.
   GET /users/:id/wallet_accounts

4. 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)
   POST /wallet_accounts/:id/bill_payment

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

6. Check the wallet balance of your user to confirm funds have been sent.
   GET /wallet_accounts/:id

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

8. (Pre-Live only) You can call the same 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
   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": []
}

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 callback (webhook) service running, that your user exists and that a bpay account has been added.

1. Create an Item to move money from your to the user who will be paying the bill.
   POST /items
2. Fund the Item specifying the user’s digital wallet
   PATCH /items/:id/make_payment
3. 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

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