Virtual Accounts

Overview

This guide will run you through how to setup your users with virtual accounts which cover dedicated account numbers for your payin users.

Please refer to the following link for Virtual Accounts

Getting Started

Before you can create virtual accounts your platform will need to be enabled for this feature. Please get in touch with us to enable this feature for you.

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.
Virtual Account refers to an account number that is dedicated for one of your users. It links to your user's wallet
Payin is money being paid into the Assembly ecosystem.
ASM is shorthand for Assembly

Prerequisites
As a pre-requisite to using these APIs please ensure you have carried out the following:

Have implemented and migrated over to our OAuth authentication framework
Have implemented and migrated over to our Webhooks APIs
Have implemented and migrated over to our Asynchronous APIs

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
Setup a Webhook on the Virtual Accounts Object to be notified about the virtual account status changes
Create a virtual account for the user. As a result of this API call you will receive an account number (BSB/account number) that you can share with your user to send funds to.
Please be aware that this API currently returns HTTP 201. Starting 18th Oct 2021, this API will return asynchronous response with HTTP 202.
The details of this API are at Create Virtual Account
POST /wallet_accounts/:id/virtual_accounts
(Once off) Set up a Webhooks on the transactions object to be notified of incoming funds
POST /webhooks
(Pre-live Only) Fund a user’s digital wallet with NPP
POST /https://hooks.zapier.com/hooks/catch/6080728/boeioii/

{
    "amount": 1000, // Amount in cents
    "wallet_uuid": "Wallet ID",
    "type": "NPP" // NPP or DE
}

When your user transfer funds from their bank to the BSB/account number provided in step 5, you will receive a transactions webhook with the details of the payment. This could be a NPP or Direct Credit payment depending on the payer bank's setup. The detail of the webhook object can be found Webhooks under the examples:

NPP Payin via Virtual Account BSB and Account Number
DE Payin via Virtual Account BSB and Account Number

Please note that the transactions object you will receive using the webhook and using GET /transactions will not contain payin detailed information as these details have moved to the Supplementary Data API. You can retrieve more details of the transaction by calling the following API Transaction supplementary data (Production Only) to view details of the Direct Credit or NPP payin you received such as the sender bank account details

Answers to general information and common questions can be found here: