Payrix Hosted Payment Page (HPP)

Hosted Payment Page

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.

Functionality of a HPP:

Accepts payment via Card, PayTo/PayID and Wallet (Apple Pay or Google Pay)
- can be set to single one-time payment with no intention to save payer data
- OR supply the ‘savepayer’ paramater set to ‘true’ to save payer data to Payrix secure vault for ongoing payments
  - Note - Wallet Payment only available for single one-time payment
Does not accept BPAY payment
Payment submitted in real-time with real-time response

The process for using the Payrix HPP token 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 completed the form we will redirect them back to your website using the returnURL you provided when generating the token.
Call the Token Lookup API endpoint to obtain the result of the token.

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 typical API workflow is noted below:

Use the endpoint - POST Generate HPP Token
1. Redirect your customer to the URL you received with the token.
Poll Token Lookup API to identify result of HPP.
1. If Successful and one-off payment, complete
2. If rejected, implement workflow to generate a subsequent HPP token to capture payment
If Saving Payer Payment Method for future payments, charge stored card (real-time transaction) or utilise scheduling API (2 business day transaction result)

Sample API flow for successful single/one-off payment 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'
As this flow samples not saving payer data:
- ‘UniqueReference’ parameter is not required
- Set ‘SavePayer’ parameter = ‘false’ or simply do not include parameter in API request

Depending on the workflow of your application, the HPP payment can still be allocated to a Payer Reference only if a Payer Record has been created previously:

If a Payer record has been created, you can still allocate the payment to the payer by sending the ‘UniqueReference’ in the API body with ‘SavePayer’ parameter set to ‘false’. This will allow you to allocate the payment to the specific payer record when you do not want or need a DDR agreement for ongoing payments as it is a one-off payment.
If there is no Payer record in the database, and you attempt to allocate the payment to a uniqueReference that does not exist, it will prompt an error at the completion of the payment page.
- To Create a Payer Record
  - POST Add a New Payer

Refer to Token [HPP] Generate Model for more information around the API properties.

Sample

Example Request

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

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

Example Request allocated to Payer record via UniqueReference

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

Example Response

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

Example Request allocated to Payer record via UniqueReference

Sample API flow for successful HPP Payment + Save Payer Data 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'
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

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

Implement Recurring Payment solutions after Saving Payer Data via HPP

When you elect to save payer data via the Payrix HPP, the payer must agree to the Direct Debit Terms & Conditions. This allows Payrix to debit their nominated account as and when required directed by the business. To collect future payments, the Payrix platform offers 3 solutions:

Process a transaction using saved card details / charge stored card
- Processes a real-time card transaction on the card account registered to the payers account
Schedule a single payment
- A non real-time card transaction allowing you to schedule a payment to be processed on the current or future date
Schedule multiple future payments
- A non real-time card transaction allowing you to schedule multiple future payments to be processed on the current and future date

Refer to the links to implement a recurring payment solution after saving payer data:

What if a payment via the Payrix Hosted Payment Page fails or is unsuccessful?

When a payment is declined through the Payrix Hosted Payment Page, a new HPP will need to be generated. This is due to the fact that a HPP token is valid for 20 minutes and is a one-time use token. Ensure to keep this in mind when implementing your desired workflow and have a solution in place to generate a new HPP to re-attempt payment.

The API flow will be the same for a rejected payment and to keep it simple, a sample flow is below when implementing a HPP without saving payer data.

Sample API flow for failed HPP Payment

API

POST Generate HPP Token

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

Sample

Example Request

Example Response

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_REJECTED’
- Transaction statusCode = 'R - Rejected
  - Transaction subStatusCode = Provides description of rejection
- 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.

Here you can see that the Token Status and Token Event Status differ:

The Token Event was successfully completed
The Token Status displays rejected as the token status is relevant to the transaction, not the event.

Sample

Example Request

Example Response

This concludes the API workflow of implementing the Payrix Hosted Payment Page to your application. Refer to our other methods available for accepting payments.