Virtual Accounts


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

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

  1. Check if a ​user​ already exists in Assembly
    GET /users/:id
  2. Create ​user​ in Assembly if it doesn’t exist in step 1.
    POST /users
  3. Update ​user​ in Assembly if it does exist in step 1.
    PATCH /users/:id
  4. Get the ​digital wallet​ account ID for the user
    GET /users/:id/wallet_accounts
  5. Setup a Webhook on the Virtual Accounts Object to be notified about the virtual account status changes
  6. 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
  7. (Once off) Set up a Webhooks on the transactions​ object to be notified of incoming funds
    POST /webhooks
  8. (Pre-live Only) Fund a user’s digital wallet with NPP
    POST /
    "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:

  1. What personal user details are needed to create a virtual account?
  2. How many virtual accounts can be created for a user?

Did this page help you?