How to Implement PayTo Payments

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.

This product is currently in early stages of release. Please reach out to your Partner Manager at Payrix to discuss availability and timeline.

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:

1. Add a New Payer

   1. A payer record must be created firstly in order to have a PayTo Agreement created.

   2. Use this endpoint to create a payer record and map the payer between your application and Payrix.

2. Agreement Create

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

3. Agreement Lookup

   1. Returns the full details, including the current status, of the agreement with the given reference.

4. Payment Submit

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

      1. Note that the agreement must be in the ACTIVE status for payments to be able to be processed for it.

5. Payment Lookup

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

6. Agreement Status Update

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

7. Setup Webhooks

   To set up webhooks for testing and production the below will need to be setup:

   1. Webhook Url: You provide us a single URL (must be https://) to which we will POST all our web messages for all event types.

   2. 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: Payrix Integrations/Implementations team will provide the credentials to you for testingTo set up webhooks for testing and production the below will need to be setup:

        1. Webhook Url: You provide us a single URL (must be https://) to which we will POST all our web messages for all event types.

        2. 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: Payrix 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:

• Testing Help Desk in Sandbox Portal

Step 1 - Add a New Payer

Step 2 - Agreement Create

Agreement Input Model

• AgreementUniqueReference (string) [Required] - A reference/ID that will uniquely identify this particular agreement within your systems. Must be unique for each business.

• PayerUniqueReference (string) [Required] - 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.

• PayerName (string - 64 max length) [Required] - The full name of the person or business that is going to be making the payments.

• PayerIsBusiness (bool) - set this to true if the payer is a business rather than an individual person [Default: False].

• Description (string - 140 max length - basic alpha numeric text only) [Required] - 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.

• AgreementPurpose (enum) [Required] - Specifies the general purpose of the payments for this agreement.

  • Allowed values:

    • DEPD - Dependent Support Payments

    • GAMP - Gambling Payments

    • GOVT - Government Payments

    • LOAN - Loan Payments

    • MORT - Mortgage Payments

    • OTHR - Other Service Payments

    • PENS - Pension Payments

    • PERS - Personal Payment

    • RETL - Retail Payments

    • SALA - Salary Payments

    • TAXS - Tax Payments

    • UTIL - Utility Payments

• PayIDType (enum) [Required] - The type of Pay ID that the payer has provided.

  • Allowed values:

    • EMAL - Email address

      • Required format: A valid single email address.

        • Must match regex: ^(?:[a-z0-9!#$%&'+/=?^_{|}~-]+(?:\\.[a-z0-9!#$%&'*+/=?^_{|}~-]+)@(?:a-z0-9?\.)+a-z0-9?)$

    • TELI - Telephone Number

      • Required format: Starts with "+" followed by the country code (from 1 to 3 digits) then a "-" followed by any combination of numbers (e.g. +61-417123456).

        • Must match regex: ^\+[0-9]{1,3}-[1-9]{1,1}[0-9]{1,29}$

    • AUBN - Australian Business Number

      • Required format: A 9 or 11 digit number.

        • Must match regex: ^((\d{9})|(\d{11}))$

    • BBAN - Australian Bank Account number

      • Required format: Numeric digits only with BSB (6-digits) followed by Account Number.

        • Must match regex ^(\d){10,16}$

• PayID (string) [Required] - The Pay ID that the payments will be debited from. It’s value must match the type specified in PayIDType (see above for format requirements for each type).

• PaymentAmountType (enum) [Required] - The way in which payment amounts will be calculated for this agreement.

  • Allowed values:

    • BALN - Balloon - Regular payment amounts are fixed with a large final payment amount.

    • FIXE - Fixed - Ongoing payments are always fixed to the same amount.

    • USGB - Usage Based - Payment amount varies based on service usage.

    • VARI - Variable - Payment amounts are always variable and are at the discretion of the business.

• PaymentAmount (decimal) [Conditional] - The standard payment amount of all payments for this agreement.

  • Is [Required] when PaymentAmountType is FIXE

• PaymentAmountMax (decimal) [Conditional] - The maximum amount that can be processed per payment.

  • Is [Required] when PaymentAmountType is VARI or USGB

• PaymentAmountFirst (decimal) - Set this if the first payment amount is going to be different from the regular ongoing amounts.

• PaymentAmountLast (decimal) - Set this if the last payment amount is going to be different from the regular ongoing amounts.

• ValidFromDate (date) [Required] - Date from which the agreement comes into effect and payments can start to be processed on it.

• ValidToDate (date) [Conditional] - Date by which the agreement will be finalized and the final payment for this agreement is expected to have been processed.

  • Is [Required] when AllowAutomaticExtension is false

  • Must be set to null when AllowAutomaticExtension is true

• FrequencyType (enum) [Required] - The frequency by which payments will be processed for this agreement.

  • Allowed values:

    • ADHO - Adhoc

    • ONEO - One-off

    • INDA - Intra-Day

    • DAIL - Daily

    • WEEK - Weekly

    • FRTN - Fortnightly

    • MNTH - Monthly

    • QURT - Quarterly

    • MIAN - 6 Monthly

    • YEAR - Annually

• AllowAutomaticExtension (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 false then ValidToDate must be provided.

• IsAttended (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: False].

  • Note that this flag merely specifies to PayTo that you would like this agreement handled as a high priority - it doesn't guarantee that it will be processed any quicker.

• ActionRequestedByTime (date + time) - 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.

  • Note that this not enforced by PayTo - it is used only to display some sort of waiting countdown timer on the payer’s banking app to encourage them to complete it by the specified time. If you want the agreement to be voided if not accepted within a particular period, you will need to use the Agreement Status Update endpoint to cancel the agreement.

• Audit (Audit model) - Can be used to provide tracking information of the user of your system who is performing the action.

Agreement ID Model:

Response Payload

• AgreementUniqueReference - The reference you provided to identify the agreement mirrored back to you.

• AgreementID - Payrix’s 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 the AgreementUniqueReference you provided.

• 500 (Internal Server Error) - An error occurred preventing the request from being processed.

Step 3 - Agreement Lookup

Agreement Search Model

• Business (model: Business Info) - Info of the business the agreement is attached to

• Payer (model: Payer Info) - Info of the payer the agreement is attached to

• AgreementID (string) - Payrix’s unique reference/ID for this agreement.

• AgreementsStatus (enum) - Current status of the agreement.

  • Possible values:

    • UNSUBMITTED - Agreement is waiting to be submitted to PayTo for processing.

    • PENDING - The agreement has been submitted to PayTo and we are currently waiting for it to be processed and approved.

    • ACTIVE - The agreement has been approved by the payer and is ready for the processing of payments.

    • DECLINED - The payer chose to decline the terms of the agreement, so no payments are able to be processed through it.

    • SUSPENDED - The agreement has been suspended. No payments can be processed for it until the agreement is resumed/re-activated.

    • CANCELLED - The agreement has been cancelled. No further payments can be processed for it. A new agreement will need to be submitted if you want to process further payments for this payer.

    • RECALLED - Not currently used

    • EXPIRED - The agreement was not approved within the required timeframe and is now expired.

    • DISPUTED - The payer has raised a dispute relating to this agreement and/or its payments. No further payments can be processed for the agreement until the dispute is resolved.

    • ERROR - An error occurred at some point during the processing of the agreement and it is not useable. A new agreement will need to be submitted.

    • PORTING - Not currently used

    • COMPLETED - The end of the validity period specified by the terms of the agreement has been reached. A new agreement will need to be submitted if you wish to process further payments for this payer.

    • PENDING_SUSPEND - Not currently used

    • PENDING_REACTIVATE - Not currently used

    • PENDING_CANCEL - Not currently used

• AgreementUniqueReference (string) - The unique reference/ID that you provided when you registered the agreement.

• PayerUniqueReference (string)- Your unique reference/ID for the payer that the agreement is linked to.

• PayerName (string - 64 max length) - The full name of the person or business that is going to be making the payments.

• PayerIsBusiness (bool) - set this to true if the payer is a business rather than an individual person.

• Description (string - 140 max length) - Narrative describing what the payments of the agreement are paying for.

• AgreementPurpose (enum) - Specifies the general purpose of the payments for this agreement.

  • Possible values:

    • DEPD - Dependant Support Payments

    • GAMP - Gambling Payments

    • GOVT - Government Payments

    • LOAN - Loan Payments

    • MORT - Mortgage Payments

    • OTHR - Other Service Payments

    • PENS - Pension Payments

    • PERS - Personal Payment

    • RETL - Retail Payments

    • SALA - Salary Payments

    • TAXS - Tax Payments

    • UTIL - Utility Payments

• PayIDType (enum) - The type of Pay ID that the payer has provided.

  • Possible values:

    • EMAL - Email address

    • TELI - Telephone Number

    • AUBN - Australian Business Number

    • BBAN - Australian Bank Account number

• PayID (string) - The Pay ID that the payments will be debited from.

• PaymentAmountType (enum) - The way in which payment amounts will be calculated for this agreement.

  • Allowed values:

    • BALN - Balloon - Regular payment amounts are fixed with a large final payment amount

    • FIXE - Fixed - Ongoing payments are always fixed to the same amount

    • USGB - Usage Based - Payment amounts varies based on service usage

    • VARI - Variable - Payment amounts are always variable and are at the discretion of the business

• PaymentAmount (decimal) - The standard payment amount of all payments for this agreement.

• PaymentAmountMax (decimal) - The maximum amount that can be processed per payment.

• PaymentAmountFirst (decimal) - Set this if the first payment amount is going to be different from the regular ongoing amounts.

• PaymentAmountLast (decimal) - Set this if the last payment amount is going to be different from the regular ongoing amounts.

• ValidFromDate (date) - Date from which the agreement comes into effect and payments can start to be processed on it.

• ValidToDate (date) - Date by which the agreement will be finalized and the final payment for this agreement is expected to have been processed.

• FrequencyType (enum) - The frequency by which

  • Possible values:

    • ADHO - Adhoc

    • ONEO - One-off

    • INDA - Intra-Day

    • DAIL - Daily

    • WEEK - Weekly

    • FRTN - Fortnightly

    • MNTH - Monthly

    • QURT - Quarterly

    • MIAN - 6 Monthly

    • YEAR - Annually

• AllowAutomaticExtension (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.

• IsAttended (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.

• ActionRequestedByTime (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.

• CreatedTime (DateTime) - Date/time on which the agreement was first submitted.

• LastUpdateTime (DateTime) - Date/time when the last status update occurred on this agreement.

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

PayTo Payment Model

• Reference (string(100)) - Unique reference you provide to identify the transaction (must be unique across all your transactions of all types).

• Amount (decimal) - Amount of the transaction (include decimal point for currencies with cents).

• Audit (Audit model) - Can be used to provide tracking information of the user of your system who is performing the action.

PayTo Payment ID Model

• Reference (string) - The reference you provided mirrored back to you.

• TransactionID (string) - Payrix’s 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 the Reference you provided.

• 500 (Internal Server Error) - An error occurred preventing the request from being processed.

Step 5 - Payment Lookup

Agreement Payment Search Model

• Business (model: Business Info) - Info of the business the payment is attached to.

• Payer (model: Payer Info) - Info of the payer the payment is attached to.

• Time (DateTime) - Date/time when payment was originally submitted for processing.

• Reference (string) - The unique reference you provided when you submitted the payment.

• AgreementUniqueReference (string) - The unique reference of the agreement the payment is attached to.

• PaymentID (string) - Payrix’s unique payment ID/reference.

• AgreementID (string) - Payrix’s unique agreement ID/reference.

• Amount (decimal) - The amount of the transaction that has been processed by the bank.

• AmountRequested (decimal) - The transaction amount you initially specified to be processed (this will match the Amount parameter above unless payer-paid fees were added to the transaction).

• StatusCode (enum: Transaction Status) - Code of the current status of the transaction.

• SubStatusCode (enum: Transaction Sub Status) - 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).

• LastUpdateTime (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

Agreement Status Update Model

• ChangeToStatus (enum) - The status that you want to change the agreement to.

  • Allowed values:

    • CANCEL - Cancel the agreement.

    • SUSPEND - Suspend the agreement.

    • RESUME - Reactivate a previously suspended agreement.

• ReasonDescription (string - 128 max length - basic alphanumeric text only) - Can be used as a narrative to describe the reason for the status change.

• Audit (Audit model) - 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:

1. Webhook Url: You provide us a single URL (must be https://) to which we will POST all our web messages for all event types.

2. 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: Payrix 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 Payrix, 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:

• Id (string) - A GUID providing a unique ID for identifying this particular webhook. This can be used for duplicate checking.

• EventTime (DateTime) - Date/time when the event triggering the webhook occurred.

• EventType (enum) - The event that occurred which the webhook is a notification of. Will be one of the following:

  • npp_payto_agreement_active

  • npp_payto_agreement_amended

  • npp_payto_agreement_cancelled

  • npp_payto_agreement_declined

  • npp_payto_agreement_disputed

  • npp_payto_agreement_error

  • npp_payto_agreement_pending

  • npp_payto_agreement_recalled

  • npp_payto_agreement_resolution

  • npp_payto_agreement_resumed

  • npp_payto_agreement_suspended

  • npp_payto_agreement_timeout

  • npp_payto_payment_disputed

  • npp_payto_payment_error

  • npp_payto_payment_pending

  • npp_payto_payment_rejected

  • npp_payto_payment_resolution

  • npp_payto_payment_successful

  • npp_payto_payment_refunded

• Transaction (model: Transaction Search) - If the event relates to a particular transaction, the details of the transaction are provided here.

• Payer (model: Payer Info) - If the event relates to a particular payer, the details of the payer are provided here.

• Agreement (model: Agreement Search) - If the event relates to a particular PayTo Agreement, the details of the agreement are provided here.

• SentTime (DateTime) - Date/time when the webhook was first sent.

• Timestamp (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

1. Once an agreement has been created you can simulate PayTo Agreement Acceptance, Decline or Cancel by following the below steps:

   1. Log in to Sandbox Portal

   2. Once logged in, click on PayTo heading

   3. Search for Agreement and Click View

   4. 

   5. Then click ‘Action Agreement’

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

   7. 

Trigger successful or failed payment

1. Once a PayTo payment has been submitted, you can simulate a successful or failed payment result by following the below steps:

   1. Log in to Sandbox Portal

   2. Once logged in, click on PayTo heading

   3. Search for Agreement and Click View

   4. 

   5. When you enter the agreement page, Click View in the ‘Payment History’ section

   6. 

   7. Once you enter the Payment Details page, scroll down and use the Sandbox Self-Serve and to trigger a successful or failed payment event.

   8. 

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 with Payrix.