PayID Per User

📘

Australia only

The following guide is for platforms operating in Australia.

A PayID is a secure, easy-to-remember identifier that’s linked to an account. Utilising the PayID per user feature, you’ll reconcile payments faster and easier by registering a PayID with your user's virtual account.

How it works

You can have one or more unique PayIDs set up for your user to enable addressing NPP payins through the use of an email address. Not only is it easier to remember an email rather than a BSB and account number, but PayIDs for your users also add the security of not having to share those details every time.

Your users can send payins using the PayID to fund their wallets. They will see the name associated with the PayID to be certain who the recipient is before confirming the actual payment.

The image below shows the structural relationships, which involve:

• one wallet per user,
• one virtual account per user wallet,
• multiple PayIDs that must be linked to a virtual account.

Getting started

Before you can register PayIDs, get in touch with us to have your platform enabled for this feature.

By default, we will set up the domain name for the email IDs as your platform name. Let us know if you’d like to change it.

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.
• A virtual account is an account number that is dedicated to each of your users. It links to your user's wallet.
• PayID is a unique identifier registered with your user's virtual account.
• Payin is money being paid into the Zai ecosystem using a PayID.

Prerequisites

As a prerequisite to using the PayID APIs, please ensure that you have:

• implemented and migrated over to our OAuth authentication framework.
• implemented and migrated over to our webhook APIs.
• created a virtual account for your user.

API steps

1. Get the ​digital wallet​ account ID for the user.
   GET /users/:id/wallet_accounts
2. Get the virtual account ID for the user.
   GET /wallet_accounts/{id}/virtual_accounts
3. (Once-off) Setup a webhook on the PayID object to be notified about the PayID status changes.
4. Create a PayID for the user. As a result of this API call, the PayID will be registered with the virtual account number. You can share this PayID with your user so that they can fund their wallet with it.
   POST /virtual_accounts/{id}/pay_ids
5. (Once-off) Set up a webhook on the Transactions​ object to be notified of incoming funds through the PayID.
   POST /webhooks
6. (Pre-live only) Fund a user’s digital wallet using the PayID created in step 4.
   POST https://int-npp-master.platforms.prelive.assemblypayments.com/npp/receive-request

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

• amount - This is the amount of funds that will be sent to the user’s wallet.
  Note that 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. 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. E.g. "vaId": ""

📘

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.

7. When a user transfers funds from their bank to the PayID (provided in step 4), you will receive a transactions webhook with details of the payment. The details of the webhook object can be found in the Webhooks guide under the example, NPP Payin via PayID.

📘

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 NPP payin that you received, such as the sender's bank account details, PayID details, etc.

Deregister a PayID

With the Update PayID Status API, you can deregister the PayID if the user no longer wishes to use it. Once it’s deregistered, the PayID can no longer be used for payments. You can register the PayID again if it's needed.

📘

If a PayID has not been used for payments after a long period of time, we’ll require that you deregister the PayID. A list of unused PayIDs will be shared with you through a monthly report.

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

1. Are other PayID types supported, like phone numbers, etc?
2. Can a user have more than one active PayID associated with a virtual account?
3. Can a PayID be paused?
4. How many accounts can I link my PayID to?