Real Time Payout Workflow


This integration guide will run you through how to use Zai to do real-time payouts to your users via the NPP.
To pay your users you only need their BSB and Account Number, Zai will look these details up on the NPP network and if their account is NPP enabled (~90% of accounts are enabled) we will pay your users in real time, if your user’s bank account is not NPP enabled we can pay them using our fallback direct entry payouts (funds will land within 3 business days).

Getting Started

Before you can run your NPP workflow there are a few setup steps that need to be completed so that all of the pieces are available.

You will need to capture specific details from your users for you to be able to send funds via the NPP, the requirements for real time payouts can be ​found here​, but there is some flexibility with the specific data depending on your use case and the payment workflow (let’s chat about it).
The setup discussed in this guide makes use of a float to fund your payout. The float will require sufficient funds and periodic top-ups (​see inbound payments below​). Your funding bank account ​must allow PayID payments​, as the float is paid in by a customer reference number and PayID email address.

Terminology used
The following terminology is used throughout this guide:

  • Platform​ refers to your platform (you, your website, app, marketplace etc.).
  • User​ refers to your customer who will have a User record in Zai.
  • Item​ is the mechanism for moving funds between users in the API.
  • Payin​ is money being paid into the Zai ecosystem.
  • Payout​ is money being paid out of the Zai ecosystem to a bank account.
  • Float User ​is a User you create who hold the balance of funds you wish to payout to
    your users.
  • Callbacks are legacy implementations of webhooks.

API steps

Setup steps
We recommend that you create callbacks (webhooks) on the following objects to receive notifications from us of state and status changes.

  • Transactions
  • Items
  • Users
  • Batch Transactions
  • Accounts

To create a callback, you would call ​POST /callbacks​, more information on callbacks can be ​found here​.
Inbound payments (topping up your float - PreLive only)
The following steps allow you to add funds to a user’s digital wallet in our prelive environment. In the real world, you would sent us a payment and we would match it to the wallet. For the purposes of testing, you can add funds to wallets as needed.

  1. Create a ​user​ for your Float User.
    POST /users
  2. Get the ​digital wallet​ account ID for your Float User.
    GET /users/:id/wallet_accounts
  3. Get the NPP reference details for the user (this is just so you can add money to the account in PreLive).
    GET /wallet_accounts/:id/npp_details
  4. (Pre-live Only) Fund a user’s digital wallet with NPP.
    PATCH /testing/wallet_accounts/process_npp_payin
  "crn": "Customer reference number - reference from wallet", 
  "payid": "PayID - pay_id from wallet",
  "amount": 10000 // Amount in cents
  1. Get the digital wallet account ID and balance for your Float User.
    GET /users/:id/wallet_accounts

Outbound payments (paying your users)
These steps are how you will send funds to your users using the API from funds that are in your Float user’s digital wallet.

  1. Create a user for your customer (who you want to pay) if they don’t exist already.
    POST /users
  2. Update the user for your customer if they already exist (if needed).
    PATCH /users/:id
  3. Add a ​bank account​ for your customer (you’ll need the bank account ID in step 8).
    POST /bank_accounts
  4. Set the bank account as the disbursement (or payout) account.
    PATCH /users/:id/disbursement_account
  5. Create an ​Item​ (use Type=2) to move money from your Float User to your customer.
    POST /items
  6. Fund the Item with your Float User’s digital wallet (use the ID you got in Step 5 on the Inbound payment steps)
    PATCH /items/:id/make_payment
  7. Check the Callback payload to see how your user’s wallet was funded.
    GET /callbacks/:id/responses
  8. Create a ​withdraw​ request on the wallet to pay to your user’s nominated bank account (use the bank account ID from step 3)
    POST /wallet_accounts/:id/withdraw
    "account_id": abc 123456789,
  "custom_descriptor": "See Design Considerations - Custom Descriptors",
  "amount": 10000 // Amount in cents 

Check the Callback payload to see that the payout was completed.
GET /callbacks/:id/responses

  1. Check the wallet balance of your user to confirm funds have been sent.
    GET /wallet_accounts/:id

Design considerations

User data design
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.





zai_user_npp_crn (for payins)











Custom descriptors
For real time payouts you have the option of customising the payment description seen by your customers.
It's an extra parameter on the ​withdraw call​ named ​custom_descriptor​. You can have a string of up to 200 alphanumeric characters. It will then be prefixed by the word "Payment ".
Eg. "Payment {for transaction ID 1234567812345678}". Most banking portals already pull your platform’s name in other parts of their transaction detail.


Workflow summary
Once you’ve run through the API steps and implemented something like the above in your platform, the sequence of calls to run the payout workflow in production will be reduced.

This flow assumes that you have a callback (webhook) service running, that your user exists and that a bank account has been added, and set as a disbursement/payout account.

  1. Create an Item to move money from your Float User to your customer.
    POST /items
  2. Fund the Item with your Float User’s digital wallet (use the ID you got in Step 5 on the Inbound payment steps)
    PATCH /items/:id/make_payment
  3. Create a withdraw request on the wallet to pay to your user’s nominated bank account (use the bank account ID from step 3)
    POST /wallet_accounts/:id/withdraw

Did this page help you?