The following guide is for platforms operating in Australia.
Before you can start using PayTo, get in touch with us to have your platform enabled for this feature.
PayTo is an easy, fast, and secure digital way for your users to pay directly from their bank account instead of paying with a card or old direct debit system.
It’s an opportunity to go digital with direct debit payments for users on your platform. It helps businesses thrive in a digital economy with fast, reliable, and secure payments that keep money moving 24/7.
PayTo can be used for one-off, ad hoc, or recurring payments. Your users can use their bank account or PayID as a payment method for online purchases, to fund digital wallets, to pay recurring payments, and more.
At the core of PayTo is customer pre-authorisation of a PayTo agreement. This agreement contains the payment terms agreed between the seller and the business. PayTo agreements can be pre-authorised within a payer’s usual internet or mobile banking, where PayTo agreements can also be paused, resumed or cancelled.
Instead of creating new PayTo agreements for users using direct debit arrangements, you can migrate their existing direct debit arrangements to PayTo, which won’t require re-authorisation from your users.
Here’s a deeper dive into the benefits of PayTo for you and your users.
- Greater visibility - your users can see all businesses that are authorised to debit their bank account on their internet or mobile banking app. They can view payment terms and other details for each agreement.
- Digital - ease of use for your users because they don’t have to contact the bank directly or deal with any paper-based agreements. These are all stored digitally with NPPA and accessible to your users in their banking app.
- More control - your users can easily perform agreement maintenance functions, like pausing or cancelling an agreement directly in their online banking app.
- User-friendly - users can optionally use a personalised PayID when setting up agreement arrangements rather than keying in their BSB and Account Number.
- Communication - banks may choose to optionally deliver additional notifications to your users regarding upcoming payments to be debited from their bank account.
- Smart alternative to direct debit and cards - enable PayTo as a new payment option on your platform for online purchases, funding digital wallet, for one-off or recurring payments, and many other use-cases.
- Eliminate payment uncertainties from bank accounts with:
- Real-time validation of your user’s bank account at the time of agreement creation.
- Real-time checks of fund availability at the time of payment.
- Payment confirmations.
- Immediate response on payment instructions.
- Reduced chances of payment dishonours and disputes.
- Communication - you’ll receive notifications of any changes in the agreement, for example, if an agreement is cancelled or suspended by your user.
- Single source of truth - digital and centralised storage of agreement records with NPPA.
- More information available for each payment - you and your users will be able to see more information for each payment.
- Digital - ability to support a more seamless, digital, and efficient payments experience to your users.
The following terminology is used throughout this guide along with PayTo definitions you should become familiar with:
- PayTo agreement (sometimes referred to as a mandate)- the digital agreement that records the authorised payment terms between you and your user.
- Payment initiator - the party initiating payments based on instructions received from the initiating party. In this case, it’s Zai initiating payments based on instructions received from you.
- Direct Debit Authority (DDA) - in the Bulk Electronic Clearing System (BECS), it’s an authorisation from your user to debit their bank account for a specific amount.
- Payment terms - these are the specific terms that collectively make up a PayTo agreement. These include the following:
- Initiating Party - this being you, the party initiating the payments to be debited from your user’s bank account.
- Buyer/Debtor/Payer - your user who needs to pay funds for goods or services purchased from you or another user on your platform.
- Seller/Ultimate Creditor/Ultimate Payee - your user who needs to receive the funds ultimately for the goods or services provided through your platform (your app, marketplace, website, etc.). Note: if your platform is a provider of goods or services, then the ultimate creditor/payee would be you.
- Payment amount - amount(s) authorised by your user.
- Payment amount type - the type of agreement, for example, fixed or variable.
- Frequency - how often payments can be debited from your user’s bank account.
- Agreement type - the type of agreement, for example, migrated versus new agreements that would require your user’s authorisation.
- Description / Short description - the long or short form description of the agreement.
- Start date / End date - this defines the valid period of the agreement. Payments can be debited from your user’s bank account only within the valid period.
- First / Last payment date - the date on which the first or last payment can be debited from your user’s bank account.
Payment terms for the PayTo agreement can be loosely defined, much like many ongoing usage-based direct debit authorities. Or, the agreement can be very tightly constrained using a lot of attributes to define the restrictions, such as — start and end dates, the frequency, fixed amounts or variable amounts, etc. (The range and combination of options is quite extensive.)
Knowing this, your design should consider the pros and cons of a simple, open arrangement against a more constrained one.
A more constrained agreement may substantially increase your platform solution complexity with respect to ensuring each payment initiation request falls within the scope of the agreement constraints you include. Note that you will be held liable when such breaches result in successful claims.
- NPPA - New Payments Platform Australia
- Mandate Management System (MMS) - the digital and centralised storage of agreement records with NPPA.
- The following refers to a PayTo payment requested against an approved agreement:
- Payment Initiation Request (PIR)
- Mandate Payment Initiation Request (MPIR)
- Payment claims/disputes - claims raised by your user with their bank for any non-compliant or wrongful debits on their bank account.
- agreement_uuid - unique identifier generated by Zai for an agreement.
- agreement_id - unique identifier generated by NPPA for an agreement.
There are two types of PayTo agreements that you can create:
- Payer Authorised PayTo Agreement (AUPM type in our APIs)
- Migrated PayTo Agreement (MGCR type in our APIs)
This agreement is also referred to as an Authorised Payment Mandate (AUPM). When you initiate this type of agreement creation, users can provide their account details using either a PayID, or a BSB + Account Number.
An authorisation request is sent to your user through their bank to approve or reject the agreement based on the payment terms accepted between both of you.
Depending on the priority you set for the agreement creation action, your user’s bank may notify them immediately about the pending agreement authorisation request.
The agreement authorisation request will expire automatically (if custom expiry duration is not specified during agreement validation) after 5th day if not actioned by your user. The agreement will be cancelled automatically on 6th day if not cancelled by the payer institution on the 5th day post authorisation request expiration. You’ll then need to initiate the agreement creation process again.
Payments can be debited from your user’s bank account only after the agreement is approved. Once approved, the agreement becomes Active and is available for payment initiations.
- Set the priority of agreement creation as Attended if you want your user’s bank to notify them immediately about the pending agreement authorisation request.
- It’s recommended to verify the resolved PayID details with your user before sending us a request for agreement creation to avoid claims/disputes due to incorrect agreement setup.
This agreement is also referred to as a Migrated by Creditor (MGCR) agreement type. When you initiate this type of agreement creation, users can provide their account details using a BSB + Account Number.
If your users are already using the direct debit payment (using BECS) option on your platform, instead of creating new PayTo agreements for them, you can migrate their current Direct Debit Authority (DDA) over to PayTo.
Migrating a pre-authorised, active DDA agreement does not require any re-authorisation from your user. Such agreements will be
active immediately upon creation in the PayTo system; however, payments can only be initiated 5 days after migration.
- You must inform your user at least 14 days in advance about their current DDA agreement plan to be migrated over to PayTo. If the user doesn't object within 14 days after receiving the notice, you can proceed with the migration.
- You should make sure that the intent and scope of the PayTo agreement remains the same as the current DDA agreement during migration. The user won't be able to reauthorise the migrated agreement.
- With migrated agreements, you are only permitted to initiate individual payment requests where each request’s payment value is $5,000 AUD or less. Also assuming this amount is less than or equal to the limits, if any, migrated to the PayTo agreement from the original DDR.
You may choose to consider splitting payment requests, for example; 2 x $3,000 requests rather than a single $6,000 request; this assumes the limits set for the PayTo agreement and the original DDR, on which it relies, permit this.
Or, you may also consider creating a new PayTo agreement, that permits payment initiation requests that exceed $5,000. Such a proposed agreement would require the payer to actively approve the PayTo agreement, prior to you submitting related payment initiation requests.
- After the migration, you can’t debit your user’s bank account using the original direct debit arrangement because it's not valid post-migration. Such activity would be considered a violation and would be subject to disputes and legal issues.
PayTo agreement creation is a two-step process. You’ll need to first validate the agreement details, then you can request the creation of the agreement.
Step 1 - Validate the agreement details
As part of the agreement validation step, we verify if the details are valid, including whether your user’s bank is considered NPP and PayTo reachable, based on NPPA records.
We'll also return the bank account name associated with your user’s PayID. We recommend that you confirm the bank account name with your user before requesting agreement creation. This confirmation by the user of a valid PayID can reduce the chances of setting up incorrect agreements and disputes.
The agreement validation step is designed to mitigate the risk of setting up incorrect agreements. As part of the validation process, we verify if your user's bank is NPP and PayTo reachable; however, it's possible that the user's account may not be NPP or PayTo reachable yet. In this case, validation will be successful, but agreement creation will fail.
Over time, the reliability of this validation step will improve. But for now, you should design for the edge case whereby an agreement could be validated successfully, but the creation may fail due to the user's account not being reachable via PayTo.
If the agreement creation fails, you should inform the payer user that their bank hasn't enabled PayTo yet on their bank account. The payer user would then need to talk to their bank to enable PayTo for their bank account.
Step 2 - Request agreement creation
You should request agreement creation immediately, within 5 minutes after successful validation. This will trigger a notification to your user through their bank to approve or reject the agreement.
After approval by your user, the agreement will then be
active and available for payment initiations.
Authorisation requests that are pending approval with your user are only applicable for the AUPM agreement type.
If the agreement creation isn’t requested within 5 minutes after successful validation, you’ll need to validate the agreement again.
Details of an agreement your users will see in their banking app:
|Payer/Buyer user on your platform||BSB + Account Number or|
PayID (Not applicable for migrated agreements)
|Payee/Seller user on your platform||Your platform name (if you are the provider of goods/services directly) or|
the seller user’s name on your platform.
|Initiating Party||Your platform name or|
any third party name that you prefer to be shown to your user as initiator of the payments instead of you.
After agreement approval by your user, you can then initiate PayTo payment requests to collect funds from your user’s bank account. You can also retry any previous payment initiation requests that were rejected due to a valid business reason.
We initiate fund collection from your user’s bank account only after receiving instructions from you. The initiation request will be accepted by us only if it’s requested for a valid agreement. This means that the date of the payment request is between or the same as the agreement validity, start and end date.
To avoid payment claims/disputes and PayTo rule breaches, it's important to call the Initiate PayTo Payment API (and any retries) strictly as per the terms and conditions established in the agreement.
Once funds have been collected from your user’s bank account, the inbound payment is matched to the user and matched with the digital wallet that's associated with the buyer user on your platform. Through webhooks, we’ll notify you about the arrival of funds in the wallet. You can then create an Item to move the funds from the buyer’s wallet on your platform to the seller user’s wallet.
- Set the priority of payment initiation request as Attended if you want it to be executed immediately. This means that if your user's bank isn't reachable due to technical issues, we'll reject the request and notify you immediately about it.
- If your user’s bank is not reachable, payment initiation requests with the priority set as Unattended, may be stored and processed later rather than rejecting them.
Below are some important points to be aware of about payment initiation requests, including contractual obligations that apply to you as a customer of Zai:
- You should initiate the payment requests as per the agreement terms and conditions to avoid being liable for non-compliant payments. We do not initiate payment requests for you unless requested to do so. This means that you are responsible for initiating the payment request with the correct date, time, and amount as per the agreement.
- You can retry a payment initiation request if the previous request is rejected due to valid business reasons.
There may be times where an edge case arises, such as an agreed catchup payment for a missed instalment. For example, if your agreement is defined with a monthly frequency and the payer user agrees a one-off extra payment is necessary or desired, you need to consider whether requesting the extra payment would reasonably be interpreted as you acting in accordance with the intent of the approved agreement or not. You should understand that in such cases, you're at increased risk of a breach call or claim. So, you should ensure you (your user) have sufficient records regarding customer permission to support the defence of such a claim.
- You're liable for agreement claims/disputes, if any are raised by your users for non-compliant payments. The claim amount can be more than the actual amount debited (your users can include any losses incurred due to non-complaint debits).
Below webhook events will be sent for a PayTo agreement (payto_agreements object). Refer the webhooks guide for sample notification payloads.
|Webhook Event Type||Notification Purpose|
|AGREEMENT_CREATION_SUCCESS||Agreement created successfully and is waiting debtor's approval|
|AGREEMENT_CREATION_FAILURE*||Agreement creation failed due to internal processing issues. Please contact Zai support if you receive this notification|
|AGREEMENT_ACTIVATION_SUCCESS||Agreement has been approved by the debtor|
|AGREEMENT_ACTIVATION_FAILURE*||Agreement activation failed due to internal processing issues. Please contact Zai support if you receive this notification|
|AGREEMENT_REJECTION_SUCCESS||Agreement has been rejected by the debtor|
|AGREEMENT_EXPIRATION_SUCCESS||Agreement authorisation request expired as the debtor did not authorise within the specified timeframe|
|AGREEMENT_PAUSE_SUCCESS||Agreement status updated successfully (ACTIVE -> SUSPENDED)|
|AGREEMENT_PAUSE_FAIL*||Agreement status update failed due to internal processing issues. Please contact Zai support if you receive this notification|
|AGREEMENT_RESUME_SUCCESS||Agreement status updated successfully (SUSPENDED -> ACTIVE)|
|AGREEMENT_RESUME_FAIL*||Agreement status update failed due to internal processing issues. Please contact Zai support if you receive this notification|
|AGREEMENT_CANCELLATION_SUCCESS||Agreement status updated successfully (ACTIVE -> CANCELLED)|
|AGREEMENT_CANCELLATION_FAIL*||Agreement status update failed due to internal processing issues. Please contact Zai support if you receive this notification|
|AGREEMENT_AMENDMENT_SUCCESS||Agreement details (unilateral or bilateral) updated successfully|
|AGREEMENT_AMENDMENT_REJECTION_SUCCESS||Agreement details (bilateral) amendment authorisation request has been rejected by the debtor|
|AGREEMENT_AMENDMENT_EXPIRATION_SUCCESS||Agreement details (bilateral) amendment authorisation request expired as the debtor did not authorise within the specified timeframe|
|AGREEMENT_AMENDMENT_FAIL*||Agreement amendment failed due to internal processing issues. Please contact Zai support if you receive this notification|
|AGREEMENT_RECALL_SUCCESS||Agreement creation or agreement amendment (bilateral) request has been recalled successfully|
|AGREEMENT_RECALL_REJECTED||Agreement creation or agreement amendment (bilateral) request cannot be recalled as either the current agreement status is not valid or the debtor has already authorised/rejected the request|
Webhook notifications marked with "*" are extremely rare events and should not occur normally. If you ever receive such a notification type, please contact Zai support.
Below webhook events will be sent for a PayTo payment initiation request (payto_payments object). Refer the webhooks guide for sample notification payloads.
|Webhook Event Type||Purpose|
|PAYMENT_INITIATION_COMPLETED||PayTo payment cleared and settled successfully between the payer and payee financial institutions. Funds have been collected from the debtor's bank account successfully and are yet to be reconciled in the user's wallet (Zai buyer wallet)|
|PAYMENT_INITIATION_REJECTED||PayTo payment requested has been rejected due to various business reasons. Refer API swagger docs for the list of rejection reasons|
Below webhook events will be sent for a PayTo payment transaction (transaction_failure_advice object). Refer the webhooks guide for sample notification payloads.
|Webhook Event Type||Purpose|
|transaction_failure_advice||PayTo payment cleared and settled successfully between the payer and payee financial institutions however the funds cannot be reconciled on the user's wallet (Zai buyer wallet) due to some issues. Funds collected from the debtor's bank account will be refunded back automatically in such cases.|
Updated about 2 months ago
Get started with Zai's APIs for PayTo in a sandbox environment.