Simulate PayTo APIs in Sandbox

📘

Australia only

The following guide is for platforms operating in Australia.

To ensure that you’re integrating accurately with Zai’s APIs for PayTo before deployment to the production environment, use our Pre-live sandbox environment to simulate and test end-to-end payment flows for PayTo. This guide helps you walk through those available workflows.

📘

Please note

Keep in mind while going through these API steps that a PayTo agreement isn’t created with NPPA, nor does an angreement actually go to the payer or approver. A funds collection request is not sent to the payer’s bank account, therefore, there is no collection of funds.

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. Create ​a user​ in Zai if it doesn’t exist already. Note: A digital wallet account is generated automatically with User creation.
   POST /users

2. (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 on 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.

3. Call the Validate PayTo Agreement API to validate the agreement details before creation with NPPA.

• Simulate payer rejection for the agreement (expected agreement status: cancelled).
  Pass "REJECT_AGREEMENT" keyword in the “description” field during validation step.
• Simulate payer approval for the agreement (expected agreement status: active).
  If anything apart from "REJECT_AGREEMENT" keyword is provided in the “description” field, it would simulate the payer approval for the agreement.

4. Call the Get PayTo Agreement Details API to verify whether the agreement has been validated successfully or not.
   Note: Zai does not send any webhook notifications during the validation step to inform you about the validation success or failure.

5. If payer account details are provided using PayID, the resolved PayID details (PayID owner name) will be available from the Get PayTo Agreement Details API(“payid_name”).

6. Invoke the Create PayTo Agreement API immediately within 5 minutes, post-successful validation.
   When you call this API, we will initiate the agreement creation and notify you through a webhook notification whenever the agreement status changes from pending_creation -> created or pending_creation -> creation_failed (if the creation fails due to any reason).

7. After successful creation, NPPA forwards the agreement to the payer’s institution to seek your user’s approval. As this is sandbox environment, we simulate user’s approval/rejection based on keywords passed in the “description” field (step 3). We'll notify you through the webhook notification whenever the agreement status changes from created to active or cancelled.

8. Invoke Initiate PayTo Payment API to simulate funds collection from your user’s bank account as per the agreement terms and conditions. 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.
   As this is a sandbox environment, funds collection from user’s bank account is simulated using keywords in the payment initiation request as below:

• Simulate payment rejection with no retry possibility (expected payment initiation request status: payment_initiation_rejected).
  In the payment initiation request, pass "REJECT_PAYMENT_NO_RETRY" keyword in the “remittance_info” field.
• Simulate payment rejection with retry possibility (expected payment initiation request status: payment_initiation_rejected).
  In the payment initiation request, pass "REJECT_PAYMENT_WITH_RETRY" keyword in the “remittance_info” field.
• Simulate payment initiation successful completion (expected payment initiation request status: payment_initiation_completed).
  In the payment initiation request, pass any value apart from "REJECT_PAYMENT_WITH_RETRY" or “REJECT_PAYMENT_NO_RETRY” keywords in the “remittance_info” field.

9. If the payment is initiated successfully in step 8, we reconcile the received funds on your user’s digital wallet account (created in step 1). 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:

• Basic details - Show Transaction API
• Additional details - Show Transaction Supplementary Data API

10. If the payment is rejected in step 8, depending on the rejection reason, you can retry the same payment again by providing retry info in the request (do not pass rejection related keywords in the remittance field to simulate the retry attempt as successful) or initiate a new payment to simulate funds collection from your user’s bank account.

11. If the payment initiation is successful, but if we were not able to match the funds to your user’s wallet, we'll immediately initiate a refund for the payment. In such cases, we’ll notify you about the reconciliation failure through a webhook notification on the transaction_advice_failure object. Once the reconciliation fails, fetch the failed PayTo payment details using the Failed NPP Payment Details API. You can also simulate the failure to reconcile funds on your user's wallet as below:

• Simulate failure to match funds on user's wallet (expected payment initiation request status: payment_initiation_completed).
  In the payment initiation request, pass "FAIL_FUNDS_UPDATE_ON_USER_WALLET" keyword in the “remittance_info” field.

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

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

2. (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 on 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.

3. Call the Validate PayTo Agreement API to validate the agreement details before creation with NPPA.

4. Call the Get PayTo Agreement Details API to verify whether the agreement has been validated successfully or not.
   Note: Zai does not send any webhook notifications during the validation step to inform you about the validation success or failure.

5. If agreement validation is successful as per step 4, call the Create PayTo Agreement API immediately within 5 minutes post-validation.
   When you call this API, we will initiate the agreement migration and notify you through a webhook whenever the agreement status changes from pending_creation -> active or pending_creation - > creation_failed (if the creation fails due to any reason).

6. Post-successful migration, invoke the Initiate PayTo Payment API to simulate funds collection from your user’s bank account as per the agreement terms and conditions. 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.
   As this is a sandbox environment, funds collection from a user’s bank account is simulated using keywords in the payment initiation request as below:

• Simulate payment rejection with no retry possibility (expected payment initiation request status: payment_initiation_rejected).
  In the payment initiation request, pass "REJECT_PAYMENT_NO_RETRY" keyword in the “remittance_info” field.
• Simulate payment rejection with retry possibility (expected payment initiation request status: payment_initiation_rejected).
  In the payment initiation request, pass "REJECT_PAYMENT_WITH_RETRY" keyword in the “remittance_info” field.
• Simulate payment initiation successful completion (expected payment initiation request status: payment_initiation_completed).
  In the payment initiation request, pass any value apart from "REJECT_PAYMENT_WITH_RETRY" or “REJECT_PAYMENT_NO_RETRY” keywords in the “remittance_info” field.

7. If the payment is initiated successfully in step 6, we reconcile the received funds on your user’s digital wallet account (created in step 1). 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:

• Basic details - Show Transaction API
• Additional details - Show Transaction Supplementary Data API

8. If the payment is rejected in step 6, depending on the rejection reason, you can retry the same payment again by providing retry info in the request (do not pass rejection related keywords in the remittance field to simulate the retry attempt as successful) or initiate a new payment to simulate funds collection from your user’s bank account.

9. If the payment initiation is successful, but we were not able to match the funds to your user’s wallet, we'll immediately initiate a refund for the payment. In such cases, 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.

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 (payer).

3. We'll 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.
   As this is sandbox environment, user (payer) actions can be simulated using the below keywords passed in the amendment request:

• Simulate payer rejection for the bilateral amendments requested.
  Pass "REJECT_AMENDMENT" keyword in the “_transferarrangement” field in the amendment request.
• Simulate bilateral amendment request expiration.
  Pass "EXPIRE_AMENDMENT" keyword in the “_transferarrangement” field in the amendment request.
• Simulate payer approval for the bilateral amendments requested.
  Pass anything apart from keywords "EXPIRE_AMENDMENT" or “REJECT_AMENDMENT” in the “_transferarrangement” field in the amendment request.

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