You can add PayTo to your existing integration. The following instructions show only what you must add to your integration specifically for PayTo.
If an instruction on this page corresponds with a step in the main integration guide, it includes a link to that corresponding step of the main integration guide.
Requirements
| Requirement | Description | |
|---|---|---|
| Integration type | Make sure that you have an existing API-only integration. This page includes only instructions to add PayTo to your existing integration. |
|
| Checkout API | Make sure that you use Checkout API v70 or later. | |
| Action handling | Make sure that your existing integration is set up to handle the additional action. action.type: await. |
|
| Setup steps | Before you begin, add PayTo in your Customer Area. |
Get PayTo as an available payment method
When you make the /paymentMethods to get available payment methods, specify the following so that PayTo is included in the response.
| Parameter | Values |
|---|---|
| countryCode | AU |
| amount.currency | AUD |
| shopperReference | Optional. Your shopper's unique ID to retrieve their stored payment methods. |
Build your payment form
We provide the logo for PayTo that you can download.
Include PayTo in the list of available payment methods. You do not need to collect any information from the shopper in your payment form.
Add additional parameters to your /payments request
When you make a payment, add the following parameters:
The additional parameters that you include depends on the type of payment.
One-time payment
For one-time payments, add the following additional parameters.
| Parameter | Required | Description | |
|---|---|---|---|
| paymentMethod |  |
payto | |
| paymentMethod.shopperAccountIdentifier | |
The shopper's banking details or PayID reference, used to complete the payment. Possible values. 1 | |
| shopperName.firstName | |
The shopper's first name. | |
| shopperName.lastName | |
The shopper's last name. | |
| shopperStatement | The text that shows up on the shopper's statement. | ||
| lineItems.quantity | The number of items From 0 to 9999. | ||
| lineItems.sku | Up to 200 characters. | ||
| lineItems.description | Used to display the payment statement description to the shopper. Up to 280 characters. If multiple items, the item descriptions will be appended with a "," separator. |
||
| lineItems.amountIncludingTax | From 1 to 100000000. | ||
| lineItems.itemCategory | Up to 200 characters. | ||
| reference | The reference to uniquely identify a payment. We recommend using a unique value per payment; however, it is not a requirement. Up to 35 characters. |
The response includes:
Subscription setup and first payment
To set up a subscription agreement with specific conditions and accept the first payment from the shopper, add the following parameters.
| Parameter | Required | Description | |
|---|---|---|---|
| paymentMethod | |
payto | |
| paymentMethod.shopperAccountIdentifier | |
The shopper's banking details or PayID reference, used to complete the payment. Possible values. 1 | |
| shopperName.firstName | |
The shopper's first name. | |
| shopperName.lastName | |
The shopper's last name. | |
| storePaymentMethod | |
Set to true to store payment details for subscription payments. | |
| recurringProcessingModel | |
Subscription | |
| shopperInteraction | |
Ecommerce | |
| mandate.frequency | |
The frequency with which a shopper should be charged. Possible values: adhoc, daily, weekly, biWeekly, monthly, quarterly, halfYearly, yearly. adhoc: Suitable for Card On File and Unscheduled Card On File recurring processing models. daily, weekly, biWeekly, monthly, quarterly, halfYearly, yearly: Suitable for Subscription recurring processing model. |
|
| mandate.endsAt | |
End date of the billing plan, in YYYY-MM-DD format. | |
| mandate.amount | |
The billing amount (in minor units) of the recurring transactions. 1 to 1000000000. | |
| mandate.amountRule | |
The limitation rule of the billing amount. Possible values: max: The transaction amount can not exceed the amount. exact: The transaction amount should be the same as the amount. |
|
| mandate.remarks | |
The agreement description shown to the shopper up to 140 characters. | |
| mandate.startsAt | Start date of the billing plan, in YYYY-MM-DD format. By default, the transaction date. | ||
| mandate.count | The number of transactions that can be performed within the given frequency. Conditions: If the frequency is different than adhoc the count has to be provided and should be >= 1If frequency is adhoc the count can be omitted or will represent the total number of payments that can be done. |
||
| shopperStatement | The text that shows up on the shopper's statement. Appears in Mandate Remarks in One-off payment flow, if no Remarks are provided. | ||
| lineItems.quantity 1 | From 0 to 9999. | ||
| lineItems.sku 1 | Up to 200 characters. Note that this field is only available from v70 onwards. | ||
| lineItems.description 1 | Used to display the payment statement description to the shopper. Up to 280 characters. If multiple items, the item descriptions will be appended with a "," separator. |
||
| lineItems.amountIncludingTax 1 | From 1 to 100000000. | ||
| lineItems.itemCategory 1 | Up to 200 characters. | ||
| reference | The reference to uniquely identify a payment. We recommend using a unique value per payment; however, it is not a requirement. Important: For PayTo, only up to 35 characters. |
1 The lineItems information are consolidated and provided to PayTo as the payment description, and can be shown in the shopper's banking app (depending on the bank's capabilities).
The following example shows a payment request that gives the shopper a subscription agreement with a first payment of 30 AUD and a weekly payment of up to 90 AUD.
| Parameter | Example value | Description |
|---|---|---|
amount.value |
3000 | After the shopper accepts the subscription agreement, they make a first, immediate payment of 30 AUD. |
mandate.frequency |
weekly | A payment must be made weekly. |
mandate.amount |
9000 | The amount of the weekly payment. |
mandate.amountRule |
max | The maximum amount of the weekly payment is the mandate.amount of 90 AUD. |
mandate.count |
1 | The shopper can make only one payment each week. |
mandate.endsAt |
2025-12-31 | The subscription agreement ends on December 31, 2025. |
mandate.remarks |
Your agreement description | The description of the agreement that appears in the shopper agreement. |
The response includes:
The shopper receives a notification from their bank (through SMS, email, or in their banking app) to authorize or decline the agreement.
When the subscription agreement is accepted, you get the RECURRING_CONTRACT webhook that includes the recurringDetailReference for subsequent subscription payments.
Subsequent subscription payment
For a subsequent subscription payment, add the following parameters.
| Parameter | Required | Description |
|---|---|---|
| paymentMethod | |
payto |
| paymentMethod.storedPaymentMethodId | |
From the recurring.token.created webhook associated with the shopper, the data.storedPaymentMethodId. This stored payment method can only be used according to the conditions specified in the subscription agreement. |
| shopperInteraction | |
ContAuth |
| reference | The reference to uniquely identify a payment. We recommend using a unique value per payment; however, it is not a requirement. Important: For PayTo, only up to 35 characters. |
The response includes:
Shopper account identifiers
The following table shows the possible values you can use for the shopperAccountIdentifier parameter.
| Identifier | Regular expression (RegEx) for allowed values |
|---|---|
|
BSB-AccountNumber |
|
|
PayID Email |
|
|
PayID Phone Number |
|
|
PayID ABN |
|
|
PayID Organisation Identifier |
|
Required webhooks
The following webhook notifications indicate the status of the transaction.
OFFER_CLOSED
This notification will be returned when the agreement failed or is canceled by the user.
In this case, the refusalReasonRaw will be included in the additionalData object in the format errorCode:errorDescription. The contents of refusalReasonRaw will provide details about the reason for the failure or cancellation. Process the refusalReasonRaw to obtain more information about the decline or cancellation reason.
AUTHORISATION
You will receive this notification for a payment on an accepted agreement, the payment outcome could be authorized or rejected.
In case the payment fails due to an error, you can consume the refusalReasonRaw that is returned in the additionalData object of your notification to get additional information about the reason for the payment being refused.
REFUND
When the refund is successfully received, the outcome will most likely succeed unless you receive a REFUND_FAILED notification.
REFUND_FAILED
Because refunds are asynchronous events, the outcome might fail due to unexpected reasons. In such cases you will receive a REFUND_FAILED notification.
RECURRING_CONTRACT
Contains the token in the payload of the notification sent to you in the pspReference parameter.
DISABLE_RECURRING
When an agreement arrives to term, or is canceled (by you or the shopper), you will receive a DISABLE_RECURRING notification to keep you informed about a token deletion.
Token lifecycle webhooks are also supported.
Test and go live
To test, use the shopperAccountIdentifier with the following emails to simulate testing scenarios:
| Type | shopperAccountIdentifier | Result | Description |
|---|---|---|---|
| Agreement | [Any valid input] | Authorised | Successful payment. |
| [email protected] | OFFER_CLOSED | The Agreement has expired, please request your shopper to pay again. | |
| [email protected] | OFFER_CLOSED | The agreement has been refused. | |
| Payment | [Any valid input] | Authorised | Successful payment. |
| [email protected] | Refused | Insufficient Funds | |
| [email protected] | Refused | The Shopper account is closed. | |
| [email protected] | Error | NPP is unable to process the payment due to back office issues or outage. |