Virtual Accounts

📘

Australia only

The following guide is for platforms operating in Australia.

With a virtual account linked to your user's digital wallet, you can:

• automatically match, reconcile, and track incoming NPP and DE payins. Unreconciled NPP payins are returned instantly.
• let your customers send payments to a unique BSB and account number so that you have visibility of all incoming payins.
• easily track where your money has come from.
• have a higher payment success rate with fewer rejections.

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

Getting Started

Before you can create virtual accounts, get in touch with us to have your platform enabled for this feature.

The following terminology is used throughout this guide:

• Platform​ refers to you as a customer, or your website, application, marketplace etc.
• User​ refers to your customer who will have a User record in Zai.
• 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 Zai ecosystem using a BSB and virtual account number.

Prerequisites

As a prerequisite to using these APIs, please ensure you have:

• implemented and migrated over to our OAuth authentication framework.
• implemented and migrated over to our Webhooks APIs.

API steps

1. Check if a ​user already exists in Zai.
   GET /users/:id
2. Create ​user​ in Zai if it doesn’t exist in step 1.
   POST /users
3. Update ​user​ in Zai 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 using it.
   POST /wallet_accounts/:id/virtual_accounts
7. (Once-off) Set up a webhook 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 https://int-npp-master.platforms.prelive.assemblypayments.com/npp/receive-request

{
    "amount": <Number>,
    "payId": <String>,
    "remittanceInformation": <String>,
    "vaId": <BSBandVANumber>
}

• amount - This is the amount of funds that will be sent to the user’s wallet. The Payin amount in the request should be in cents. For example, $20.00 should be represented as 2000.

• payId - This should be the PayId (type: EMAIL) that's been configured for the corresponding Virtual Account ID. When using a PayID + Customer Reference Number (CRN), the payId field should be the marketplace's PayID. And for PayID Per User, it should be the user's payID.

• remittanceInformation - This is the CRN of the wallet account to be funded.

• vaId - This is a combination of the BSB + Virtual Account Number. For example, vaId: [BSB][Virtual Account Number].

📘

For NPP Payins using the Virtual Accounts flow

payId and remittanceInformation can be empty. For example "". Only vaId and amount can be passed in the request.

When your user transfers 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 an NPP or direct credit payment depending on the payer bank's setup. The detail of the webhook object can be found in the Webhooks guide under the examples:

• NPP payin using a Virtual Account BSB and Account Number
• DE payin using a Virtual Account BSB and Account Number

📘

The transactions object you will receive using the webhook and GET /transactions will not contain payin detailed information because these details have moved to the Supplementary Data API.
You can retrieve more details of the transaction by calling the API, Show Transaction Supplementary Data (in the production environment only). This allows you to view details of the direct credit or NPP payin that you received, such as the sender's 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?