Accept PayTo Payments through own payment page - [Australia only]
Introduction
This document will guide you through the PayTo Payments platform which is a new way for businesses to initiate near real-time payments from bank accounts.
Steps
In order to begin and understand the API workflow of creating agreements and submitting payments via PayTo, the typical API flow is outlined below:
A payer record must be created firstly in order to have a PayTo Agreement created.
Use this endpoint to create a payer record and map the payer between both platforms.
Use this endpoint to register a new PayTo Agreement. The approval, processing and acceptance of the new agreement is performed asynchronously - you will need to be subscribed to our PayTo Agreement event webhooks to be notified of whether the agreement was approved by PayTo and whether or not your customer has accepted the agreement.
Returns the full details, including the current status, of the agreement with the given reference.
This endpoint will submit a new PayTo Payment for an existing agreement. The processing of the new payment is performed asynchronously - you will need subscribe to our PayTo Payment event webhooks to be notified of the result of the transaction.
Note that the agreement must be in the ACTIVE status for payments to be able to be processed for it.
Returns the full details, including the current status, of the PayTo Payment with the given reference. Only payments processed within the last 6 months can be looked up using this method - use Transaction Search for older payments.
Can be used to update the status of an existing agreement. The processing of the status change is performed asynchronously - you will need subscribe to our PayTo Agreement event webhooks to be notified as to whether or not the status change was successful.
To set up webhooks for testing and production the below will need to be setup:
Webhook Url: You provide us a single URL (must be https://) to which we will POST all our web messages for all event types.
Shared Secret:
Production: This is a randomly generated 88-character string that is unique to your business which we will generate and provide to you.
Sandbox: Our Integrations/Implementations team will provide the credentials to you for testing
To test agreement acceptance and trigger payment results, please follow our guide documented below:
Step 1 - Add a New Payer
API |
---|
Refer to Payer Input Model for more information around the API properties. |
Sample |
---|
Example Request
JSON
JSON
Example Response
JSON
|
Step 2 - Agreement Create
API |
---|
** = Conditional (Required if property is specific value) Refer to Agreement Input Model for more information. Refer to Agreement ID Model for more information.
|
Sample |
---|
Example Request
JSON
JSON
Example Response
JSON
|
Agreement Input Model
Property | Type | Description |
---|---|---|
| string | A reference/ID that will uniquely identify this particular agreement within your systems. Must be unique for each business. |
| string | Each agreement must be attached to a Payer that you have previously registered - set this field to your unique reference/ID for one of your existing payers to enable it to be linked. |
| (string - 64 max length) | The full name of the person or business that is going to be making the payments. |
| bool | set this to true if the payer is a business rather than an individual person [Default: False]. |
| (string - 140 max length - basic alpha numeric text only) | Narrative describing what the payments of the agreement are paying for. Should be concise and clearly recognizable by the payer to encourage them to accept the agreement. |
| enum | Specifies the general purpose of the payments for this agreement. Allowed values: |
| enum | The type of Pay ID that the payer has provided. Allowed values:
|
| string | The Pay ID that the payments will be debited from. It’s value must match the type specified in |
| enum | The way in which payment amounts will be calculated for this agreement. Allowed values: |
| decimal | The standard payment amount of all payments for this agreement. Is [Required] when |
| decimal | The maximum amount that can be processed per payment. Is [Required] when |
| decimal | Set this if the first payment amount is going to be different from the regular ongoing amounts. |
| decimal | Set this if the last payment amount is going to be different from the regular ongoing amounts. |
| Date | Date from which the agreement comes into effect and payments can start to be processed on it. |
| Date | Date by which the agreement will be finalized and the final payment for this agreement is expected to have been processed. Is [Required] when |
| enum | The frequency by which payments will be processed for this agreement. Allowed values: |
| bool | If this agreement is being set up with a fixed end date, this can be set to true to indicate that the agreement can be renewed under the same terms for a new period after the end date is reached. If set to |
| bool | Set this flag to true if you have a scenario where you want the agreement to be processed and approved as quickly as possible, such as where you are creating agreements as part of a process where you must wait in real-time for your customer to approve an agreement before proceeding [Default:
|
| DateTime | This can be used to specify to your customer that you want them to complete their approval of the agreement by this specified date/time.
|
| model: Audit | Can be used to provide tracking information of the user of your system who is performing the action. |
Agreement ID Model:
Response Payload
Property | Type | Description |
---|---|---|
| string | The reference you provided to identify the agreement mirrored back to you. |
| string | Our unique ID of the agreement |
HTTP Statuses - Agreement Create
202 (Accepted)
- The request has been submitted for processing. Result will be provided via webhook.400 (Bad Request)
- Request didn’t pass validation check, or your business is not properly configured/enabled for processing PayTo Agreements.409 (Conflict)
- Duplicate request - there is already an agreement registered with theAgreementUniqueReference
you provided.500 (Internal Server Error)
- An error occurred preventing the request from being processed.
Step 3 - Agreement Lookup
API |
---|
Refer to Agreement Search Model for more information |
Sample |
---|
Example Request
JSON
Example Response
JSON
|
Agreement Search Model
Property | Type | Description |
---|---|---|
| model: Business Info | Info of the business the payment is attached to. |
| model: Payer Info | Info of the payer the payment is attached to. |
| DateTime | Date/time when payment was originally submitted for processing. |
| string | The unique reference you provided when you submitted the payment. |
| string | The unique reference of the agreement the payment is attached to. |
| string | Our unique payment ID/reference. |
| string | Our unique agreement ID/reference. |
| decimal | The amount of the transaction that has been processed by the bank. |
| decimal | The transaction amount you initially specified to be processed (this will match the |
| Code of the current status of the transaction. | |
| Secondary code for the current status of the transaction that can provide more information on that particular status (only some types of transactions will have a sub status). | |
| DateTime | Date/time on which the last status update on this payment was processed. |
HTTP Statuses - Agreement Lookup
200 (OK)
- The agreement was found and returned as the payload.400 (Bad Request)
- Request didn’t pass validation check, or your business is not properly configured/enabled for processing PayTo Agreements.404 (Not Found)
- No existing agreement with the agreement reference provided was found.500 (Internal Server Error)
- An error occurred preventing the request from being processed.
Step 4 - Payment submit
API |
---|
Refer to PayTo Payment Model and PayTo Payment ID model below for more information |
Sample |
---|
Example Request
JSON
JSON
Example Response
JSON
|
PayTo Payment Model
Property | Type | Description |
---|---|---|
| string (100) | Unique reference you provide to identify the transaction (must be unique across all your transactions of all types). |
| decimal | Amount of the transaction (include decimal point for currencies with cents). |
| model: Audit | Can be used to provide tracking information of the user of your system who is performing the action. |
PayTo Payment ID Model
Property | Type | Description |
---|---|---|
| string | The reference you provided mirrored back to you. |
| string | Our unique transaction ID. |
HTTP Statuses - Payment Submit
202 (Accepted)
- The request has been submitted for processing. Result will be provided via webhook.400 (Bad Request)
- Request didn’t pass validation check, the agreement is not in the ACTIVE status, or your business is not properly configured/enabled for processing PayTo Agreements.404 (Not Found)
- No existing agreement with the agreement reference provided was found.409 (Conflict)
- Duplicate request - there is already an transaction registered with theReference
you provided.500 (Internal Server Error)
- An error occurred preventing the request from being processed.
Step 5 - Payment Lookup
API |
---|
Refer to Agreement Payment Search Model for more information |
Sample |
---|
Example Request
JSON
Example Response
JSON
|
Agreement Payment Search Model
Property | Type | Description |
---|---|---|
| model: Business Info | Info of the business the payment is attached to. |
| model: Payer Info | Info of the payer the payment is attached to. |
| DateTime | Date/time when payment was originally submitted for processing. |
| string | The unique reference you provided when you submitted the payment. |
| string | The unique reference of the agreement the payment is attached to. |
| string | Our unique payment ID/reference. |
| string | Our unique agreement ID/reference. |
| decimal | The amount of the transaction that has been processed by the bank. |
| decimal | The transaction amount you initially specified to be processed (this will match the |
| Code of the current status of the transaction. | |
| Secondary code for the current status of the transaction that can provide more information on that particular status (only some types of transactions will have a sub status). | |
| DateTime | Date/time on which the last status update on this payment was processed. |
HTTP Statuses - Payment Lookup
200 (OK)
- The payment was found and returned as the payload.400 (Bad Request)
- Request didn’t pass validation check, or your business is not properly configured/enabled for processing PayTo Agreements.404 (Not Found)
- No existing payment with the reference provided was found.500 (Internal Server Error)
- An error occurred preventing the request from being processed.
Step 6 - Agreement Status Update
API |
---|
Refer to Agreement Status Update Model for more information If a PayTo Agreement is suspended the PayTo Agreement cannot be resumed by the business. It must be resumed by the account holder. If a PayTo agreement is cancelled by the account holder, the PayTo agreement cannot be re-activated. A new PayTo agreement must be created and accepted by the accountholder. |
Sample |
---|
Example Request
JSON
JSON
Example Response This request does not return any response body |
Agreement Status Update Model
Property | Type | Description |
---|---|---|
| enum | The status that you want to change the agreement to. Allowed values: |
| string - 128 max length (basic alphanumeric text only) | Can be used as a narrative to describe the reason for the status change. |
| model: Audit | Can be used to provide tracking information of the user of your system who is performing the action. |
HTTP Statuses - Agreement Status Update
202 (Accepted)
- The request has been submitted for processing. Result will be provided via webhook.400 (Bad Request)
- Request didn’t pass validation check, or your business is not properly configured/enabled for processing PayTo Agreements.500 (Internal Server Error)
- An error occurred preventing the request from being processed.
Step 7 - Setup Webhooks
To set up webhooks for testing and production the below will need to be setup:
Webhook Url: You provide us a single URL (must be https://) to which we will POST all our web messages for all event types.
Shared Secret:
Production: This is a randomly generated 88-character string that is unique to your business which we will generate and provide to you.
Sandbox: Our Integrations/Implementations team will provide the credentials to you for testing.
To prove a webhook is a legitimate and unaltered message that was sent by us, and is intended for you, we include a signature which must be validated using a shared secret.
When we send you a webhook we will look for a successful (2xx) HTTP Status response from your web app. If we receive it we will consider the webhook successfully delivered. If we receive a status other than 2xx, or if we are unable to connect to your webhook URL, we will attempt to deliver the webhook an additional 3 times using the following back-off frequency:
1st Retry - After 30 minutes.
2nd Retry - After 2 hours.
3rd Retry - After 24 hours.
Our webhook message can contain one of more data objects depending on the event type. The data provided in the webhook is the current status of that entity at the time the webhook is generated. In general, determining what change occurred can be deduced just from the
EventType
itself, with the data object(s) only needed to get the ID/Reference to match to the entity in your system.In some situations (e.g. connection dropouts or timeouts), a webhook might be delivered to you multiple times. We provide a unique Message ID with each webhook which you can use for duplicate checking.
In some situations (e.g. if a webhook is unable to be delivered on first attempt), webhooks might be delivered out of sequence. For some event types, before actioning a webhook, it might be prudent to check the current status of the related entities in your system to make sure processing the webhook would not cause an invalid workflow. We provide timestamps with each webhook which can be useful for determining sequencing.
Webhook Messages
Our webhook messages are delivered with the following:
HTTP Headers
The following HTTP headers are included with each webhook:
x-payrix-id
- A GUID providing a unique ID for identifying this particular webhook. This can be used for duplicate checking.x-payrix-timestamp
- Unix/Epoch time (milliseconds since 01/01/1970) for when the webhook was generated. Can be used for event sequencing.x-payrix-signature
- Base-64 encoded HMAC-SHA256 signature. This must be used to verify the legitimacy of the message by taking the entire POST body of the message and performing your own HMAC-SHA256 calculation using your shared secret and checking that the value you get matches the signature.
HTTP POST Body
The payload of the message is a JSON rendering of the Webhook Message Model
described below.
Webhook Model
All our webhooks, for all event types, share a single overall data model. This model includes one or more sub-models depending on the types of entities that were affected by the event the webhook is reporting.
Webhook Message Model
with the following fields:
Property | Type | Description |
---|---|---|
| string | A GUID providing a unique ID for identifying this particular webhook. This can be used for duplicate checking. |
| DateTime | Date/time when the event triggering the webhook occurred. |
| enum | The event that occurred which the webhook is a notification of. Will be one of the following: |
| model: Transaction Search | If the event relates to a particular transaction, the details of the transaction are provided here. |
| model: Payer Info | If the event relates to a particular payer, the details of the payer are provided here. |
| model: | If the event relates to a particular PayTo Agreement, the details of the agreement are provided here. |
| DateTime | Date/time when the webhook was first sent. |
| long integer | Unix/Epoch time (milliseconds since 01/01/1970) for when the webhook was generated. Can be used for event sequencing. |
Testing Help Desk in Sandbox Portal
Action Agreement
Once an agreement has been created you can simulate PayTo Agreement Acceptance, Decline or Cancel by following the below steps:
Log in to Sandbox Portal
Once logged in, click on PayTo heading
Search for Agreement and Click View
Then click ‘Action Agreement’
Here you can use the ‘Sandbox Self-serve’ function to simulate responses to trigger agreement updates or change the status of the agreement and the sending of their associated webhooks.
Trigger successful or failed payment
Once a PayTo payment has been submitted, you can simulate a successful or failed payment result by following the below steps:
Log in to Sandbox Portal
Once logged in, click on PayTo heading
Search for Agreement and Click View
When you enter the agreement page, Click View in the ‘Payment History’ section
Once you enter the Payment Details page, scroll down and use the Sandbox Self-Serve and to trigger a successful or failed payment event.
You can use the PayTo Self-Serve function along with the standard ‘Self-Service Centre’ to run the settlement process once payments have been processed and successful/cleared.
This concludes the guide to implementing the PayTo Payments platform.