Build the merchant’s receipt page | Payroc

Create a receipt page on the merchant’s website to display the transaction response to customers.

After the customer submits their payment details, 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 there is an issue with saving the customer’s payment details, 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 URL of the merchant’s receipt page.

Important: You must provide us with a URL that we redirect your customer to when they save their payment details. This URL is not the same as the receipt page URL you set up for sales and pre-authorizations.

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:

Sign in to the Self-Care Portal:
- Test: https://payments.uat.payroc.com/merchant/selfcare/
- Production: https://payments.payroc.com/merchant/selfcare/
From the side menu, select Settings, and then select Terminal.
In the Secure Token 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 saved their card details or their bank account details.

You must program your integration to associate the MERCHANTREF and CARDREFERENCE parameters with the customer. You can use MERCHANTREF to look up the token in your merchant’s database, and you use CARDREFERENCE instead of the customer’s payment details in follow-on transactions.

Query parameters

Parameter	Type	Size	Description
RESPONSECODE	Enum		Response code from our gateway. The value is one of the following: - `A` - We stored the payment details. - `E14` - We couldn’t store the card details because we couldn’t validate them. - `E43` - We couldn’t validate the bank details, but we stored the updated details. - `E44` - We couldn’t store the bank details because we couldn’t validate them.
RESPONSETEXT	String	1-48 characters	Description of the response code.
MASKEDCARDNUMBER	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`.
MERCHANTREF	String	1-200 characters	Unique identifier that the merchant assigns to the secure token. Note: We recommend that you store this value.
CARDHOLDERNAME	String	1-50 characters	Customer’s name.
CARDREFERENCE	String	12-19 characters	Secure token that represents the customer’s payment details. Note: We recommend that you store this value to run follow-on transactions.
CARDTYPE	String		Card brand of the card.
CARDEXPIRY	String	4 characters	Expiry date of the customer’s card. The format for this value is MMYY.
TRANSITNUMBER	String	5 characters	Five-digit number that identifies the customer’s bank branch.
ROUTINGNUMBER	String	9 characters	Nine-digit number that identifies the customer’s bank.
ACCOUNTNUMBER	String	4-17 characters	Number of the customer’s bank account. Our gateway masks all digits except the last four digits, for example, `****3159`.
ACCOUNTHOLDER_NAME	String	1-29 characters	Customer’s name.
INSTITUTIONNUMBER	String	3 characters	Three-digit number that identifies the customer’s bank.
ACCOUNTTYPE	Enum		Indicates the customer’s account type. The value is one of the following: - `CHECKING` - `SAVINGS`
DATETIME	String		Date and time that the customer submitted their payment details. Our gateway returns this value in DD-MM-YYYY:HH:MM:SS:SSS format, for example, `06-02-2026:12:23:23:719`.
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]:[RESPONSECODE]:[RESPONSETEXT]:[MERCHANTREF]:[CARDREFERENCE]:[DATETIME]:[SECRET]`
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.
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.
BRANDTXIDENTIFIER	String	1-64 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.