BPAY Payin Workflow

Overview

This integration guide will run you through how to use BPAY to directly fund a user’s digital wallet with Assembly.
Provide BPAY deposit details to your customers, once they provide funds to the BPAY account, Assembly 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 be completed so that all of the pieces are available.

Terminology used
The following terminology is used throughout this guide:

Platform refers to your platform (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

API steps

Check if a user already exists in Assembly
GET /users/:id
Create user in Assembly if it doesn’t exist in step 1.
POST /users
Update user in Assembly 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	asm_user_id	asm_bank_account_id	asm_digital_wallet_id	asm_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	asm_item_id	asm_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 Assembly if it doesn’t exist in step 1.
POST /users
Update user in Assembly 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