How to Implement Wallet Payments via Payrix HPP

Overview

Wallet Payments for Apple Pay and Google Pay allow users the ability to submit a payment via Apple Pay or Google Pay through the Payrix Hosted Payment Page (HPP). This functionality is only available for one-time payments via the Payrix HPP and available with the Pay Now invoices for Xero.

Please note, if the page or payer is not eligible for a wallet type payment, they will still be presented with the ability to pay using full card details.

Key notes

Wallet Payments only available for single real-time transactions.

• Not available when electing to save the payer details.

  • Wallet Payments can be linked to an existing payer record

  • "SavePayer" property must be set to false or not included in the body of the HPP token.

• Minimum “Payer” property field requirements to satisfy Wallet Payment:

  • Supply the 3 minimum required payer fields via API to pre-populate the contact details as seen in example JSON below

    • familyOrBusinessName

    • givenName

    • Email

  • OR send through an empty “Payer” property body in order for the payer to enter their contact details directly on the payment page.

Example JSON:

    "Payer": {
    "familyOrBusinessName":"Surname",
    "givenName":"FirstName",
    "Email": "test@test.com"
    },

• 3-D Secure Authentication not compatible with Wallet Payments.

• Same refund rules apply as refunding a card transaction:
  o Via our refund card transaction API call specifying the transactionId
  o Via the Payrix Payment Portal
  o Via contacting Payrix Client Success team

Please note - Wallet Payments currently only available for merchants processing within Australia and New Zealand for certain configurations. Contact your Partner manager to confirm if this is available for your integration.

Wallet Payment Compatibility

	Available
REST API HPP	√
REST API HPP + Custom Disbursement	√
REST API HPP + Save payer	×
SOAP API HPP Note - wallet payments are not compatible through JavaScript or Transparent Redirect. You will need to send a ‘0' value for parameter ‘javascriptSubmit’ or 'transparentRedirect’ for wallet payment to be available.	√
HPP Olite	×
HPP Salesforce – Pay Now	√
HPP Salesforce – Recurring	×
HPP Simple Invoice	√
HPP Payment Recovery	×
Xero – Pay Now	√
Xero - Recurring	×

Implementing the use of Wallet Payments via the Payrix HPP

Wallet transaction via Payrix HPP

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 process for using the Payrix HPP token is simply:

1. Call the POST Generate HPP Token to obtain a token and a redirect URL.

2. Redirect your customer to the URL you received with the token.

3. After your customer has completed the form we will redirect them back to your website using the returnURL you provided when generating the token.

4. Call the token lookup 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.

How to determine the result of a Wallet transaction via Payrix HPP

• Within the response body of the transaction field, if the statuscode is ‘C' or 'S’, the transaction was successful.

  • If you are using Payrix merchant facility you will see a statuscode of ‘C' (Cleared - Processed by Payrix and debited from Payers account) immediately.

  • If you are using your own merchant facility, you will typically see a status of 'S' (Settled - Funds settled).

• Within the response body of the transaction field, if the statuscode is 'R', the transaction was declined with the rejection reason supplied in the status description.

  • If a transaction is rejected with a decline reason supplied by the issuer we will return this response. Refer to Transaction Sub-Status Code.

If a transaction is rejected, some decline responses by the card issuer return a generic reason, so it’s not always possible to know exactly why the payment was declined. If all of the information seems correct, it is best to have your customer contact their card issuer and ask for more information. For privacy and security, financial institutions are only obligated to discuss the specifics of a declined payment with their card holder.

Payment Portal example

When a transaction has been processed via a Wallet Payment, our “Transaction Search” tab allows you to specifically search for transactions via a Wallet Payment under “Method” and selecting Apple Pay or Google Pay within the “All Methods” drop down.

You can also “View Receipt” and it will list the Wallet Payment method in the “Transaction Type” property:

Receipt View:

Apple Pay

Google Pay

API response example

To determine if the transaction was via a Wallet Payment, if the first 6 digits for the “cardNumber” value are 000000 the payment is deemed to have been paid via Wallet Payment and the Wallet Type (APPLEPAY or GOOGLEPAY) is identified through the “cardholderName”.

Q: How to test wallet payments (Apple Pay / Google Pay) in Sandbox

A: Your device will need to be linked to either Apple Pay or Google Pay in order for the type of wallet payment to be available to select on our Hosted Payment Page. Any transactions pushed through the Sandbox environment will not process / deduct funds from your account.