PayTo for API only

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

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.

Build your payment form

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.
• Subscription setup and first payment.
• Subsequent subscription 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 chars.
lineItems.description		Used to display the payment statement description to the shopper. Up to 280 chars. If multiple items, the item descriptions will be appended with a "," separator.
lineItems.amountIncludingTax		From 1 to 100000000.
lineItems.itemCategory		Up to 200 chars.

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 chars.
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 >= 1 If 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 chars. 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 chars. 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 chars.

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

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

The response includes:

Shopper account identifiers

The following table shows the possible values you can use for the shopperAccountIdentifier parameter.

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:

See also