Payrix Hosted Payment Page - PayTo

The Payrix platform offers the ability to utilise the Payrix Hosted Payment Page which is implemented via a re-direction to the Payrix Payment page. This offering is the simplest way to integrate a payment solution to your software with minimal development work required.

The functionality of a HPP with PayTo:

Payment submitted in real-time with real-time response from a PayID linked to a Bank Account
Can be for one-off or set up to for recurring ongoing payments

The process for using the Payrix HPP token for PayTo is simply:

Call the POST Generate HPP Token to obtain a token and a redirect URL.
1. Redirect your customer to the URL you received with the token.
After your customer has selected PayTo and accepts the PayTo agreement within their Banking Application, the customer will be re-directed to the returnURL you specify in the API request.
After the re-direction to the returnURL is triggered, call the Token Lookup API endpoint to obtain the result of the token.
1. If Successful, the one-off payment is complete
2. If rejected, implement workflow to generate a subsequent HPP token to capture payment

Please note the token is valid for 20 minutes. You may wish to use a landing page to trigger this if the page will not be completed as part of the flow.

For example - if your application intends to supply the customer an email of an invoice with a payment link, you will need a landing page to trigger the HPP as the token is only valid for 20 minutes.

The API workflow for recurring ongoing PayTo payments contains a few more steps:

You will need to ensure your application is subscribed to our PayTo Payment and Agreement event webhooks to be notified of the result of the transaction and whether the change in status of the PayTo agreement was successful.

Use the endpoint - POST Generate HPP Token
1. Re-direction to returnURL triggered with completion of HPP
Poll Token Lookup API to identify result of HPP and record the “agreementuniqueReference” within the “nppPayID” property.
1. If Successful and one-off payment, complete
2. If rejected, implement workflow to generate a subsequent HPP token to capture payment
To submit following payments in future, use the endpoint POST Payment Submit.
1. You will need subscribe to our PayTo Payment event webhooks to be notified of the result of the transaction.
2. If the PayTo Agreement has been cancelled by the account holder, capture payment via a new HPP.
  1. If PayTo is selected, a new PayTo agreement is created.
  2. If Card is selected, you can process a transaction using saved card details to capture future payments.
Alternatively, you can call the GET Payment LookUp endpoint to identify result of PayTo transaction
1. If the payment submission was rejected, re-attempt payment capture
  1. Depending on the rejection code, you may need to contact the payer to resolve the issue to prevent further declines.
Should your merchant wish to change the status of the PayTo Agreement to either Suspend, Cancel or Resume the Agreement, the process is outlined in Step 5.

Sample API flow for one-off PayTo payments via Payrix Hosted Payment Page (HPP)

API

POST Generate HPP Token

Minimum HPP property requirements:
- ‘ReturnUrl’
- ‘Template’
- ‘Transaction’
- ‘Payer’
  - Minimum fields in Payer Property:
    - ‘FamilyorBusinessName’
    - ‘GivenName’
    - ‘Email'

Sample

Example Request

{{url}}/businesses/{{business-id}}/services/tokens/hpp/

"ReturnUrl": "https://www.payrix.com.au?txn=123456789",
    "Template": "Basic",
    "Transaction": {
      "ProcessType": "COMPLETE",
      "Reference": "PayTo Payment Reference",
      "Description": "Test HPP API Token",
      "Amount": 23.00
    },
    "Payer": {
      "FamilyOrBusinessName": "Surname",
      "GivenName": "First Name",
      "Email": "payer.hpp.1@payrix.com.au",
         },
    "Audit": {
      "Username": "Token Example",
      "UserIP": "1.2.3.4"
    }
  }'

Example Response

{
  "token": "28e24e60-0fb8-44e2-918e-e38e038e52f3",
  "redirectToUrl": "https://sandbox.paymentsapi.io/ui/hpp/api/28e24e60-0fb8-44e2-918e-e38e038e52f3"
}

Next Steps once page is completed and submitted

API

Call the Token Lookup API endpoint to obtain the result of the token.

Trigger this API call when the paying customer has been re-directed to the returnURL, allowing up to 5 - 10 seconds to retrieve response and update your application with the results.
As this example is part of a successful payment flow, take note of the below:
- Token Status property = ‘PROCESSED_SUCCESSFUL’
- Transaction statusCode = 'C' - Cleared
- Token Event Status = ‘WAITING’, ‘VALIDATED’, ‘PROCESSED_SUCCESSFUL’

Please note the token event and token event status do not relate to the same meaning:

The Token Event is specifically in relation to the token event.
The Token Status displays the status relevant to the transaction, not the event.

Sample

Example Request

Example Response

That completes the flow of one-time PayTo payment.

Sample API flow for recurring / ongoing PayTo payments via Payrix Hosted Payment Page

Step 1: Generate HPP token and re-direction

API

POST Generate HPP Token

Minimum HPP property requirements:
- ‘ReturnUrl’
- ‘Template’
- ‘Transaction’
- ‘Payer’
  - Minimum fields in Payer Property:
    - ‘FamilyorBusinessName’
    - ‘GivenName’
    - ‘Email'
To save payment details for future payments there are further requirements in the API request:
- Minimum requirement when saving payer:
  - ‘UniqueReference'
  - ‘FamilyorBusinessName’
  - ‘GivenName’
  - ‘Email’
- Set ‘SavePayer’ parameter = ‘true’
- This will create a Payer Record in the database and store the payer’s payment details securely in the Payrix Vault to allow for future debits.

Sample

Example Request

Example Response

Step 2: Token Lookup

API

Call the Token Lookup API endpoint to obtain the result of the token.

Trigger this API call when the paying customer has been re-directed to the returnURL, allowing up to 5 - 10 seconds to retrieve response and update your application with the results.
As this example is part of a successful payment flow, take note of the below:
- Token Status property = ‘PROCESSED_SUCCESSFUL’
- Transaction statusCode = 'C' - Cleared
- Token Event Status = ‘WAITING’, ‘VALIDATED’, ‘PROCESSED_SUCCESSFUL’

Please note the token event and token event status do not relate to the same meaning:

The Token Event is specifically in relation to the token event.
The Token Status displays the status relevant to the transaction, not the event.

Sample

Example Request

Example Response

This completes the initial transaction. To capture subsequent payments, follow the steps 3 and 4 below.

Step 3: Trigger next payment with POST Payment Submit

API

POST Payment Submit

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.

Sample

Example Request

Example Response

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 4: Determine result of payment with GET Payment LookUp

API

GET Payment Lookup

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.

When a PayTo payment is submitted the transaction status will either be:
- 'P' (Pending = pending response from account holders bank)
- ‘C’ (Cleared = Successful)
- 'R' (Rejected - Failed transaction)
  - If a transaction is rejected with a decline reason supplied by the issuer we will return this response. Refer to Transaction Sub-Status Code.
On the 2nd business day, the statuscode will change to 'S' when the funds have been settled.

Sample

Example Request

Example Response

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 5: Update PayTo Agreement Status

API

PUT Agreement Status Update

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.

Sample

Example Request

Example Response

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.

How to 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: 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.

How to test PayTo via Payrix HPP

Action Agreement

Once a HPP has been generated and you select PayID as the payment option, complete the page by selecting PayID Type and PayID information:
You will be directed to this page below, do not click Continue at this time:
Next Log in to Sandbox Portal
1. Once logged in, click on PayTo heading
2. Search for Agreement via the Payer Reference you specified in the API request then view the Agreement by click the icon on the right hand side as highlighted in yellow below:
4. From here, click ‘Action Agreement’
5. 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.
6. 1. If the PayTo agreement is accepted, headback to the original HPP link and click continue and follow the next steps below to trigger a successful or failed payment.
  2. If the PayTo agreement is declined, the payer will be returned to the HPP to re-attempt payment via Card or PayID.

Next step - Trigger successful or failed payment

Once you trigger the PayTo Acceptance above, you will need to trigger a successful or failed payment to simulate the payment flow in Sandbox.
1. Log in to Sandbox Portal
2. Once logged in, click on PayTo heading
3. Search for Agreement and Click View
5. When you enter the agreement page, Click View in the ‘Payment History’ section
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.

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 through the Payrix HPP.