Real Time Payin Workflow

Overview

This integration guide will run you through how to use Real Time payments (which uses the NPP banking technology) to directly fund a user’s digital wallet with Zai.

For your customers to send funds via this payment method, they need to enter your PayID details into their internet banking portal. The banks often refer to this as 'pay anyone' or 'PayID'. Once those funds arrive (in near real-time), we will notify you via a webhook (callback) and you can move those funds via an Item as needed.

Getting Started

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

Prerequisites
You will need to provide specific details to your users for them to be able to send funds via the NPP including both a PayID unique to your platform as well as their individual reference number. If the funds they send us cannot be matched, they will be automatically returned to their account and no callback will be thrown for that user.

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 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.

API steps

  1. Check if a ​user​ exists in Zai already
    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. Get the Osko/NPP reference details for the user
    GET /wallet_accounts/:id/npp_details
  6. (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,
  "payee_name": "Name of the payee",
  "trn": "CTBAAUSNXXXN20200211010124845368000" // Industry Reference,    
    "clearing_system_transaction_id": "CTBAAUSNXXXN20200211010124845368000" // Industry Reference
    "debtor_name": "Test Debtor User",
    "debtor_legal_name": "Test Debtor Legal Name",
    "debtor_bsb": "062212",
    "debtor_account": "06221293921393",
    "remittance_information": "Customer reference number - reference from wallet"
    "pay_id_type": "/EMAL"
    "end_to_end_id": "NOTPROVIDED"
    "npp_payin_internal_id": "4ba75200-4c9b-11ea-aa0f-6551300d670d" // any guid,
  "pay_id":"PayID - pay_id from wallet",
}
  1. (Once off) Set up a ​Callback​ (webhook) on the transactions​ object to be notified of incoming NPP funds
    POST /callbacks
"object_type": "transactions",
  1. Create ​Item​ (use Type=2) to pay the Payin account from the user’s account.
    POST /items
  2. Fund the ​Item​ with the user’s ​digital wallet​ account.
    PATCH /items/:id/make_payment

Design considerations

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.

User data design

your_customer_id

zai_user_id

zai_bank_account_id

zai_digital_wallet_id

zai_user_npp_crn

10001001

5b8f59b6-32c1-44a3-8f5b-b9e2c77bc265

fb35b028-76fb-44df-86ac-822dccf1cd7d

dcdfdb78-27e7-485d-90c0-11ffbf950d72

1000023456

10001002

efe6f8c1-0a30-484a-b085-9d9d0539dbfc

4355de7b-18c2-4892-b800-b7bbb6f0a9b3

054cd04e-19f1-4938-908b-8e9e5c212f4d

1000098653

Payin data design
Once you’ve run through the API steps, and implemented something like the above in your platform, the sequence of calls to run the Payin's workflow in production will be reduced to:

  1. Create user in Zai if it doesn’t exist in step 1.
    POST /users
  2. Update user in Zai if it does exist in step 1.
    PATCH /users/:id
  3. Catch the callback when the user’s digital wallet is funded via NPP.
  4. Create Item to pay the Payin account from the user’s account.
    POST /items
  5. Fund the Item with the user’s digital wallet account.
    PATCH /items/:id/make_payment

your_payin_id

zai_item_id

zai_batch_transaction_id

30001001

1563db1c-add2-4dcd-ae20-5 ad3802bf1c4

1ddb9cbb-90a7-41c6-bbbe-0 5e44f3134f1

30001002

f827dbb5-ba17-4241-a282-1 4336351faff

445bbaf3-c9bc-41aa-aec4-c 9a99944941d


Did this page help you?