Create a receipt page on the merchant’s website to display the transaction response to customers.
After the customer makes a payment, the Hosted Payment Page redirects them to the merchant’s receipt page and appends the transaction response as query parameters. The receipt page must parse these parameters and display a success or decline message.
Note: If a payment is declined, the Hosted Payment Page still redirects the customer to the receipt page and returns the response in the query parameters.
Before you begin
You must have credentials for the Self-Care Portal, which is a self-serve portal that you use to configure terminal settings for your merchant. Use this portal to provide us with the URL for the receipt page.
If you don’t have credentials for the Self-Care Portal, contact our Integrations Team at [email protected].
Integration steps
Provide us with the URL of the merchant’s receipt page.
Handle the transaction response and present the outcome to the customer.
Step 1. Provide us with the receipt page URL
Provide us with the receipt page URL in the Self-Care Portal so that we know where to redirect customers after they submit their payment details and where to send the transaction response.
To provide us with the URL, complete the following steps:
From the side menu, select Settings, and then select Terminal.
In the Receipt Page URL field, enter the URL of the receipt page.
Select UPDATE SETTINGS.
Note: Enter the receipt page URL in both the test and the production environments to ensure that you don’t have issues when you complete your testing phase and start to run live transactions.
Step 2. Handle the transaction response
The Hosted Payment Page returns the transaction response as query parameters appended to the receipt page URL. The query parameters change depending on whether the customer used their card details or their bank account details.
Card details
When a customer pays with credit card details or debit card details, the Hosted Payment Page returns the following query parameters:
Parameter
Type
Size
Description
TERMINALID
String
1-50 characters
Unique identifier that we assigned to the terminal.
ORDERID
String
1-24 characters
Unique identifier that the merchant assigned to the transaction.
APPROVALCODE
String
0-48 characters
Authorization code that the processor assigned to the transaction.
AMOUNT
Double
Subtotal of the transaction including taxes. This value doesn’t include surcharges or convenience fees.
RESPONSECODE
Enum
Response code for the transaction from the processor. The value is one of the following: A = Processor approved the transaction; E = Processor authorized the transaction (China UnionPay only); D = Processor declined the transaction; R = Processor declined the transaction and the customer should contact their bank; C = Processor declined the transaction because the payment card was reported lost or stolen.
RESPONSETEXT
String
0-48 characters
Response description from the processor.
DATETIME
String
Date and time that the processor received the request and returned a response to our gateway. We return this value in YYYY-MM-DDTHH:MM:SS format, for example, 2026-02-10T14:51:40.
AVSRESPONSE
String
1 character
Indicates if the address that the customer entered on the Hosted Payment Page matches the address linked to the card. The value is one of the following: A = First five numerical characters in the address match but the ZIP code or postal code doesn’t match; E = Transaction isn’t eligible for an AVS check; N = Address doesn’t match; R = AVS check temporarily unavailable; S = Card type not supported by AVS; U = Address information unavailable from the card issuer; G = Address information unavailable from the card issuer (Visa only); W = ZIP code or postal code matches but the street address doesn’t; X = Address matches; Y = Address matches; Z = ZIP code or postal code matches but the street address doesn’t.
CVVRESPONSE
String
1 character
Indicates if the card verification value (CVV) that the customer entered on the Hosted Payment Page matches the CVV on the card. The value is one of the following: M = CVV matches; N = CVV doesn’t match; P = CVV not processed; U = CVV isn’t registered. Note: Our gateway doesn’t automatically decline transactions when the CVV doesn’t match, unless the merchant has asked us to decline transactions where the CVV doesn’t match.
UNIQUEREF
String
10 characters
Unique identifier that our gateway assigned to the transaction. Note: Store the UNIQUEREF if you use our API for follow-on transactions, for example, to refund the transaction.
CARDREFERENCE
String
12-19 characters
Secure token that represents the customer’s payment details.
EMAIL
String
1-128 characters
Customer’s email address.
PHONE
String
5-20 characters
Customer’s phone number.
REGION
String
0-128 characters
Region of the customer’s billing address.
CITY
String
0-40 characters
City of the customer’s billing address.
POSTCODE
String
0-128 characters
Zip code or postal code of the customer’s address.
STATE
String
0-128 characters
Name of the state or state abbreviation of the customer’s billing address.
COUNTRY
String
2 characters
Two-letter code for the country of the customer’s card. The format follows the ISO 3166-1 standard.
CARDNUMBER
String
12-19 characters
Masked card number. Our gateway returns only the first six digits and the last four digits of the card number, for example, 548010******5929.
CARDHOLDERNAME
String
0-50 characters
Customer’s name.
CARDTYPE
String
Card brand of the card.
HASH
String
1-128 characters
SHA-512 hash value that we generate with values from the response parameters and the terminal secret. You can use this hash to verify that the response is legitimate. We return the hash in the following order: [TERMINALID]:[ORDERID]:[AMOUNT]:[DATETIME]:[RESPONSECODE]:[RESPONSETEXT]:[SECRET]
CUSTOMFIELD
String
Custom field that you sent in the request.
OTHERFIELD
String
0-2000 characters
Other field that you sent in the request.
BRANDTXIDENTIFIER
String
1-50 characters
Unique identifier that the card brand assigns to the transaction. If you use a third-party vault for tokenization, include this value when you use a secure token in follow-on transactions with our API, for example, to refund the transaction.
SECURECARDMERCHANTREF
String
1-200 characters
Unique identifier that the merchant assigned to the secure token.
STOREDCREDENTIALUSE
Enum
Indicates how the merchant can use the card details, as agreed by the customer: UNSCHEDULED = Transactions for a fixed or variable amount that are run at a certain predefined event; RECURRING = Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don’t have a fixed duration and run until the customer cancels the agreement; INSTALLMENT = Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. Note: We return this field only if the merchant has tokenized the card details as part of the transaction.
STOREDCREDENTIALTXTYPE
Enum
Indicates if a payment with stored card details is the first in a series of payments, or if it is a follow-on payment. The value is one of the following: FIRST_TXN = First payment in a series of payments; SUBSEQUENT_CARDHOLDER_INITIATED_TXN = Payment that the customer initiates after the first payment in the series; SUBSEQUENT_MERCHANT_INITIATED_TXN = Payment that the merchant initiates after the first payment in the series. Note: We return this field only if the customer used saved payment details for the transaction.
BYPASS_SURCHARGE
Boolean
Indicates if the merchant has bypassed surcharges for the transaction. The value is one of the following: true = Surcharges don’t apply to the transaction; false = Surcharges apply to the transaction. Note: You can’t apply surcharges to pre-authorizations.
ACCEPTTERMSANDCONDITIONS
Enum
Indicates if the customer accepted the terms and conditions for convenience fees. We return a value of ON because the customer can’t complete the transaction without accepting the terms and conditions. Note: You can’t apply convenience fees to pre-authorizations.
CONVENIENCE_FEE
Double
Convenience fee that the merchant applied to the transaction. Note: You can’t apply convenience fees to pre-authorizations.
SURCHARGE_FEE
Double
Surcharge fee that the merchant applied to the transaction. Note: You can’t apply surcharges to pre-authorizations.
SURCHARGE_PERCENT
Double
Surcharge percentage that the merchant applied to the transaction. Note: You can’t apply surcharges to pre-authorizations.
DL_NUMBER
String
0-30 characters
License number of the customer’s driver’s license.
DL_STATE
String
2 characters
Two-character abbreviation of the state that issued the customer’s driver’s license, for example, IL.
POSDEVICE
String
0-30 characters
Name of the POS device that captured the customer’s payment details.
When a customer pays with their bank account details, the Hosted Payment Page returns the following query parameters:
Parameter
Type
Size
Description
TERMINALID
String
1-50 characters
Unique identifier that we assigned to the terminal.
ORDERID
String
1-24 characters
Unique identifier that the merchant assigned to the transaction.
UNIQUEREF
String
10 characters
Unique identifier that our gateway assigned to the transaction. Note: Store the UNIQUEREF if you use our API for follow-on transactions, for example, to refund the transaction.
AMOUNT
Double
Subtotal of the transaction including taxes. This value doesn’t include surcharges or convenience fees.
TRANSITNUMBER
String
5 characters
Five-digit number that identifies the customer’s bank branch.
ROUTING_NUMBER
String
9 characters
Nine-digit number that identifies the customer’s bank.
ACCOUNT_NUMBER
String
4-17 characters
Customer’s bank account number. Our gateway returns only the last four digits of the account number, for example, *****5929.
INSTITUTION_NUMBER
String
3 characters
Three-digit number that identifies the customer’s bank.
ACCOUNTHOLDER_NAME
String
1-29 characters
Customer’s name.
ACCOUNT_TYPE
Enum
Indicates the customer’s account type. The value is one of the following: CHECKINGS = Checking account; SAVINGS = Savings account.
RESPONSECODE
Enum
Response code for the transaction from the processor. The value is one of the following: A = Processor approved the transaction; D = Processor declined the transaction.
RESPONSETEXT
String
0-48 characters
Response description from the processor.
DISCOUNT_AMOUNT
Double
Discount amount that the merchant applied to the transaction.
DATETIME
String
Date and time that the processor received the request and returned a response to our gateway. We return this value in YYYY-MM-DDTHH:MM:SS format, for example, 2026-02-10T14:51:40.
EMAIL
String
1-128 characters
Customer’s email address.
PHONE
String
5-20 characters
Customer’s phone number.
COUNTRY
String
2 characters
Two-letter code for the country of the customer’s bank account. The format follows the ISO 3166-1 standard.
HASH
String
1-128 characters
SHA-512 hash value that we generated with values from the response parameters and the terminal secret. You can use this hash to verify that the response is legitimate. We return the hash in the following order: [TERMINALID]:[ORDERID]:[AMOUNT]:[DATETIME]:[RESPONSECODE]:[RESPONSETEXT]:[SECRET]
