API Reference
Guides

PayTo APIs in Production

A walk-through guide for using PayTo APIs in your Live environment.

Suggest Edits

📘

Australia only

The following guide is for platforms operating in Australia.

Prerequisites

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

  • implemented and migrated over to our OAuth authentication framework.
  • implemented and migrated over to our webhook APIs.
  • the PayTo feature enabled for your platform.

API steps

API steps for the Payer Authorised PayTo Agreement (AUPM) setup and payment initiation

  1. Check if a user already exists in Zai.
    GET /users/:id

  2. Create ​a user​ in Zai if it doesn’t exist in step 1. Note: A digital wallet account is generated automatically with User creation.
    POST /users

  3. (Once-off) Set up webhooks on the following objects:

    • payto_agreements - to be notified about the agreement status changes.
    • payto_payments - to be notified about payment initiation request status changes.
    • transactions - to be notified of incoming funds debited from your user’s bank account and reconciled in the digital wallet that’s associated with the user.
    • transaction_failure_advice - to be notified if the PayTo payment reconciliation failed on your user's wallet.

  4. User (payer) opts for the PayTo payment option on your website. They'll provide payment terms and conditions along with their account details to you.

  5. Call the Validate PayTo Agreement API. This will do the following:

    • Verify if the user’s bank is NPP reachable
    • Verify if the user’s bank is PayTo reachable
    • Resolve PayID details of the user who's provided their account details in PayID format.

  6. Call the Get PayTo Agreement Details API to verify whether the agreement has been validated successfully or not. Use this to also get the resolved PayID details.

  7. If agreement validation is successful, confirm the resolved PayID details with your user before calling the Create PayTo Agreement API. This is to ensure your user can cross-check and confirm the PayID details before the agreement is requested for creation with NPPA.

  8. After your user (payer) confirms the resolved PayID details, then you should call the Create PayTo Agreement API immediately within 5 minutes.
    When you call this API, we create the agreement with NPPA, which then sends the agreement to your user’s bank for getting it approved from your user. We notify you whether the agreement creation with NPPA (still pending user approval) was a success or failure through the webhook notification that was set up in step 3.

  9. User (payer) approves the agreement using the banking portal. Now the agreement is active and available for payment initiations. We'll notify you about the user’s approval through the webhook notification. The agreement status changes from created to active.

  10. Initiate payment to debit your user’s bank account by calling the Initiate PayTo Payment API. We notify you about the payment initiation request status changes through a webhook notification. You can also fetch the payment initiation request status with the Get PayTo Payment Initiation Request Details API.

  11. The user’s bank accepts the payment initiation request for the agreement, then initiates a push payment with the respective amount to move the funds from your user’s bank account to us.

  12. We reconcile the received funds on your user’s digital wallet account (created in step 2). We notify you about the incoming funds on your user’s wallet through a webhook notification on the transaction object.

You can also fetch the reconciled PayTo payment details using the below APIs:

📘

Please note

If funds are received by us and we’re not able to match the inbound payment to your user, we'll immediately return the funds back to your user’s bank account.
We’ll notify you about the reconciliation failure through a webhook notification on the transaction_advice_failure object.
You can also fetch the failed PayTo payment details using the Failed NPP Payment Details API.

  1. You can create an item to move the funds from the payer/buyer user’s wallet to the payee/seller user’s wallet.

API steps for a Migrated PayTo Agreement (MGCR) setup and payment initiation

  1. Check if a user already exists in Zai.
    GET /users/:id

  2. Create a user in Zai if it doesn’t exist in step 1. Note: A digital wallet account is generated automatically with User creation.
    POST /users

  3. (Once-off) Set up webhooks on the following objects:

    • payto_agreements - to be notified about the agreement status changes.
    • payto_payments - to be notified about payment initiation request status changes.
    • transactions - to be notified of incoming funds debited from your user’s bank account and reconciled in the digital wallet that’s associated with the user.
    • transaction_failure_advice - to be notified if the PayTo payment reconciliation failed on your user’s wallet.

  4. Notify your user 14 days in advance before migrating their existing DDA agreement to PayTo. It's important to convey all aspects of the migration clearly in the notification. Please contact us for guidance on the requirements for your first migration of a direct debit agreement to PayTo.

  5. If your user hasn’t objected migration of the DDA agreement, call the Validate PayTo Agreement API. This will do the following:

    • Verify if the user’s bank is NPP reachable.
    • Verify if the user’s bank is PayTo reachable.

  6. Call the Get PayTo Agreement Details API to verify whether the agreement has been validated successfully or not.

  7. As you are migrating a pre-approved agreement, this will not trigger any approval process from your user. You should call the Create PayTo Agreement API immediately within 5 minutes. When you call this API, we create the agreement with NPPA, and the agreement is active immediately upon creation. You can, however, request payments only after 5 days for a migrated agreement. We notify you whether the agreement creation with NPPA was a success or failure through the webhook notification that was set up in step 3.

  8. Initiate payment to debit your user’s bank account by calling the Initiate PayTo Payment API. We notify you about payment initiation request status changes through a webhook notification. You can also fetch the payment initiation request status with the Get PayTo Payment Initiation Request Details API.

  9. The user’s bank accepts the payment initiation request for the agreement, then initiates a push payment with the respective amount to move the funds from your user’s bank account to us.

  10. We notify you about the incoming funds on your user’s wallet through a webhook notification on the transaction object.

You can also fetch the PayTo payment details using the below APIs:

📘

Please note

If funds are received by us and we’re not able to match the inbound payment to your user, we'll immediately return the funds back to your user’s bank account.
We’ll notify you about the failure through a webhook notification on the transaction_advice_failure object.
You can also fetch the failed PayTo payment details using the Failed NPP Payment Details API.

  1. You can create an item to move the funds from the payer/buyer user’s wallet to the payee/seller user’s wallet if needed.

API steps for amending agreement status

  1. Check if an agreement already exists and get its current status by calling the Get PayTo Agreement Details API.

  2. You can pause/resume or cancel the agreement by calling the Amend PayTo Agreement Status API. Status amendment is a unilateral change, and will not trigger any approval from your user.

🚧

You can only resume the agreement if it was suspended by you as the initiator.

  1. We notify you once the agreement status has been amended successfully or if it failed through a webhook notification on the payto_agreements object.

API steps for amending agreement details

  1. Check if an agreement already exists and get its current status by calling the Get PayTo Agreement Details API.

  2. You can amend payment terms or other details of the agreement by calling the Amend PayTo Agreement Details API. Some amendments are unilateral, which means they do not need any approval from your user. However, some amendments like, changing the payment terms, would trigger an approval process from your user. These changes, known as bilateral amendments, will only take effect upon approval by your user.

  3. We notify you once the agreement details have been amended successfully or failed through a webhook notification on the payto_agreements object.

API steps for recalling agreement creation

A debtor can authorise the AUPM agreement within 5 days (default duration) post which the authorisation request expires automatically. If the authorisation duration needs to be limited (anything less than 5 days), a custom authorisation expiry duration can be specified during the agreement validation step. This would override the default authorisation duration of 5 days.

If the debtor has not responded & the authorisation duration has elapsed, Recall API should be used to recall/cancel the pending authorisation request.

📘

Please note

Some payer banks may recall the authorisation request themselves post the duration has elapsed and some may rely on the initiator to recall the authorisation request. Hence, as a best practise, it is recommended to invoke the recall API if custom authorisation expiry duration has been specified for agreement.

Pre-requisites -

During agreement validation step, specify a custom expiry duration for the authorisation request (anything less than 5 days) via response_requested_by field.

Steps -
1. Check if an agreement already exists and get its current status by calling the Get PayTo Agreement Details API. The agreement should be in CREATED status.
2. Post the authorisation duration has elapsed, you can recall the agreement creation by Recall PayTo Agreement API.
Please Note - Few payer banks may recall the authorisation request themselves after the authorisation expiry duration has elapsed, in such case, the recall request initiated by you will fail which is expected.
3. We notify you once the agreement creation has been recalled successfully or failed through a webhook notification on the payto_agreements object.

API steps for recalling agreement details amendment request

A debtor can authorise the bilateral amendment for an AUPM/MGCR agreement within 5 days (default duration), post which the authorisation request expires automatically. If the authorisation duration needs to be limited (anything less than 5 days), a custom authorisation expiry duration can be specified in the agreement amendment request. This would override the default authorisation duration of 5 days.

If the debtor has not responded & authorisation duration has elapsed, Recall API should be used to recall/cancel the pending amendment authorisation request.

📘

Please note

Some payer banks may recall the authorisation request themselves post the duration has elapsed and some may rely on the initiator to recall the authorisation request. Hence, as a best practise, it is recommended to invoke the recall API if custom authorisation expiry duration has been specified for amendment request.

Pre-requisite -

During the agreement amendment step, specify a custom expiry duration for the authorisation request (anything less than 5 days) via response_requested_by field.

Steps -
1. Check if an agreement already exists and get its current status by calling the Get PayTo Agreement Details API. The agreement should be in either in ACTIVE or SUSPENDED status.
2. Post the authorisation duration has elapsed, you can recall the amendment request by Recall PayTo Agreement API.
Please Note - Few payer banks may recall the authorisation request themselves after the authorisation duration has elapsed, in such case, the recall request initiated by you will fail which is expected.
3. We notify you once the agreement amendment has been recalled successfully or failed through a webhook notification on the payto_agreements object.

Updated almost 2 years ago