Implement background validation | Payroc

Important: We strongly recommend that you implement background validation as part of your Hosted Payment Page integration. However, you can’t implement background validation if a customer uses bank account details as a payment method.

Background validation is a webhook-based mechanism that confirms whether our gateway processed a card payment. When you implement background validation, our gateway sends an HTTP POST request to a URL called the validation URL.

Our gateway sends a notification each time a customer submits their card details on the Hosted Payment Page, whether the payment is successful or unsuccessful. The notification is useful if the connection fails between our gateway and the merchant’s website because the notification confirms whether we received the payment.

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 validation URL.

If you don’t have credentials for the Self-Care Portal, contact our Integrations Team at [email protected].

Integration steps

Provide us with the validation URL.
Handle the webhook notification that contains the transaction response.

Step 1. Provide us with the validation URL

Provide us with the validation URL in the Self-Care Portal to inform us where to send the webhook notification.

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.
Select the Enable Validation checkbox.
In the Validation URL field, enter your validation URL.
Select UPDATE SETTINGS.

Note: Enter the validation 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 webhook notification

Each time a customer submits their card details on the Hosted Payment Page, our gateway sends an HTTP POST request to your validation URL. Your server must return the text OK in the response body to confirm that it received the notification.

If our gateway doesn’t receive an OK response, it retries the notification with exponential backoff over a 96-hour period. If all retries fail, our gateway sets the transaction to expired and sends an email to the merchant.

Each notification contains the following parameters:

Parameter	Type	Size	Description
ADDRESS1	String	0-50 characters	First line of the customer’s address.
ADDRESS2	String	0-50 characters	Second line of the customer’s address.
ALLOWHPPSCSTORAGE	String		Indicates if the customer chose to store their card details. If they stored their card details, we return a value of `ON`.
AMOUNT	Double		Subtotal of the transaction including taxes. This value doesn’t include surcharges or convenience fees.
APPROVALCODE	String	0-48 characters	Authorization code that the processor assigned to the transaction.
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. This value applies to only Visa cards. - `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.
CARDHOLDERNAME	String	0-50 characters	Customer’s name.
CARDNUMBER	String	12-20 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`.
CITY	String	0-40 characters	City of the customer’s billing address.
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.
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`.
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.
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]`
ORDERID	String	1-24 characters	Unique identifier that the merchant assigned to the transaction.
PAYLINK	String, UUID	36 characters	Indicates the UUID of the payment link that the customer used to access the Hosted Payment Page.
POSDEVICE	String	0-30 characters	Name of the POS device that captured the customer’s payment details.
POSTCODE	String	0-128 characters	Zip code or postal code of the customer’s address.
REGION	String	0-128 characters	Region of the customer’s billing address.
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. This enum applies to only China UnionPay cards. - `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.
SECURECARDMERCHANTREF	String	1-200 characters	Unique identifier that the merchant assigned to the secure token.
STATE	String	0-128 characters	Name of the state or state abbreviation of the customer’s billing address.
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.
TERMINALID	String	1-50 characters	Unique identifier that we assigned to the terminal.
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.

Example webhook notification

    POSTCODE=*******&STATE=&ORDERID=40177609&AMOUNT=40.68&REGION=Midwest&TERMINALID=12320002&CITY=Wisconsin&RESPONSETEXT=Invalid+card+number&RESPONSECODE=D&APPROVALCODE=&AVSRESPONSE=U&CVVRESPONSE=N&DATETIME=2026-04-09T09:34:46&UNIQUEREF=ABCULH4PKQ&CARDNUMBER=446261******1234&HASH=4r71bb0c4f488cb073985812ec9ccd28