Loading...
In this Hosted Payment Page (HPP) reference, we present an overview of each request type, examples of request and response values, as well as how to handle them. For more information on Fraud Management, see our Overview.
With Fraud Filter, you can supply additional information in the request that you can set rules against. This includes the customer's IP address, billing and shipping details, and specific product codes. For HPP requests, it’s also possible to change the Fraud Filter Mode in the request. This will change the mode used for the current transaction only.
For information on individual rule setting for Fraud Filter, see our Overview.
In the HPP request, you can change the Fraud Filter Mode via the optional request element Fraud Filter Mode. Additionally, you can set a Fraud Filter Mode on any individual fraud rule you choose by using the Rule ID value displayed in Ecommerce Portal. Provided the mode is set to Active in the Fraud Management section of Ecommerce Portal, it can be changed to Passive or Off in the request.
You can also supply additional information in the request that you can set rules against, such as customer billing and shipping details or specific product codes. The HPP automatically detects the customer's IP address, which can also be included.
<form action="https://pay.sandbox.realexpayments.com/pay" method="POST" target="iframe">
<input type="hidden" name="TIMESTAMP" value="20180613110737">
<input type="hidden" name="MERCHANT_ID" value="MerchantId">
<input type="hidden" name="ACCOUNT" value="internet">
<input type="hidden" name="ORDER_ID" value="N6qsk4kYRZihmPrTXWYS6g">
<input type="hidden" name="AMOUNT" value="1999">
<input type="hidden" name="CURRENCY" value="EUR">
<input type="hidden" name="AUTO_SETTLE_FLAG" value="1">
<input type="hidden" name="HPP_VERSION" value="2">
<!-- Begin Fraud Management and Reconciliation Fields -->
<input type="hidden" name="HPP_FRAUDFILTER_MODE" value="PASSIVE">
<input type="hidden" name="HPP_FRAUDFILTER_RULE_MODE_e5964ac0-ace0-477a-98ef-f467772d6a76" value="OFF">
<input type="hidden" name="CUST_NUM" value="6e027928-c477-4689-a45f-4e138a1f208a">
<input type="hidden" name="VAR_REF" value="Acme Corporation">
<input type="hidden" name="PROD_ID" value="SKU1000054">
<input type="hidden" name="BILLING_CODE" value="59|123">
<input type="hidden" name="BILLING_CO" value="GB">
<input type="hidden" name="SHIPPING_CODE" value="50001|Apartment 852">
<input type="hidden" name="SHIPPING_CO" value="US">
<!-- End Fraud Management and Reconciliation Fields -->
<input type="hidden" name="MERCHANT_RESPONSE_URL" value="https://www.example.com/responseUrl">
<input type="hidden" name="SHA1HASH" value="308bb8dfbbfcc67c28d602d988ab104c3b08d012">
<input type="submit" value="Click To Pay">
</form>Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.
Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]
| Element/Field | Category | Format | Type | Length | Description |
|---|---|---|---|---|---|
| Fraud Filter Mode | string | enum | O | N/A | Optional parameter used to determine to what degree Fraud Filter executes. If not submitted the Fraud Filter will behave in accordance with the Ecommerce Portal mode configuration. Allowed values: PASSIVE - Execute the rules but do not execute the action detailed in the Fraud Filter overall result (for example, HOLD or BLOCK) OFF - Does not execute the Fraud Filter at all for this transaction. In this case, only the mode is returned in the response. ACTIVE - Execute the action detailed in the Fraud Filter overall result for OTB transactions. |
| Customer Number | string | alphanumeric | O | 0-50 | A unique reference for this customer for example from your CRM system. Allowed special characters: [-.,+@_␣] |
| Variable Reference | string | alphanumeric | O | 0-50 | Any reference you also would like to assign to this transaction. Can also be used to pass the Acquirer Statement reference, where supported. Allowed special characters: [-.,+@_␣] |
| Product Id | string | alphanumeric | O | 0-50 | The code you assign to the product, for example the SKU. Allowed special characters: [-.,+@_␣] |
| Billing or Shipping Code | string | alphanumeric | O | 0-30 | The Postal Code concatenated with the first line of the billing or shipping address. The billing code can be used for the Address Verification Service (AVS). Allowed characters: [a-zA-Z0-9_-] |
| Billing or Shipping Country | string | alphanumeric | O | 0-50 | The country of the billing or shipping address. Allowed characters: [a-zA-Z0-9.-] |
The following extra fields will be returned in the response POST.
<!-- Additional Response Fields -->
[HPP_FRAUDFILTER_MODE=PASSIVE,
HPP_FRAUDFILTER_RESULT=BLOCK,
HPP_FRAUDFILTER_RULE_478a55db-5430-4c2a-afca-7dde181eb9f4=BLOCK,
HPP_FRAUDFILTER_RULE_NAME=Customer IP List]
HPP_FRAUDFILTER_RULE_MODE_e5964ac0-ace0-477a-98ef-f467772d6a76=OFF]| Element/Field | Category | Format | Description |
|---|---|---|---|
| Response Mode | string | enum | Indicates the mode the Fraud Filter executed in. The possible values are: ACTIVE - The rules were executed and the fraud result actioned. PASSIVE - The rules were executed but the fraud result was actioned. OFF - Fraud Filter was specifically not executed. ERROR - There was an unexpected error in executing Fraud Filter |
The Address Verification Service (AVS) verifies the cardholder's address by checking the information at the time of sale against the issuer's records.
This functionality is not supported by all issuers and is only available for cardholders in the United States, Canada, and the United Kingdom.
We support this functionality; however, not all acquirers do. For more information, contact our support team.
If a transaction fails an AVS check, it will not automatically be declined. It's an advisory service and requires that the details of non-matched transactions be checked by your application. AVS data is passed in the Billing Code field and and must be formatted correctly depending on the billing country of the cardholder. We've outlined the different formats below.
| Country | Format | Sample Address | Sample Billing Code |
|---|---|---|---|
| US or CA | Concatenate the postcode and first line of the customer's billing address with a '|' in the middle. | Flat 123 House 456 Chicago 50001 United States | "50001|Flat 123" |
| UK | Concatenate just the digits from the postcode and first line of the customer's billing address with a '|' in the middle. | Flat 456 House 123 Halifax WB3 A21 United Kingdom | "321|456" |
To submit AVS data, add the following field to the request POST. In our example, the billing country is the United States.
<form action="https://pay.sandbox.realexpayments.com/pay" method="POST" target="iframe">
<input type="hidden" name="TIMESTAMP" value="20180613110737">
<input type="hidden" name="MERCHANT_ID" value="MerchantId">
<input type="hidden" name="ACCOUNT" value="internet">
<input type="hidden" name="ORDER_ID" value="N6qsk4kYRZihmPrTXWYS6g">
<input type="hidden" name="AMOUNT" value="1999">
<input type="hidden" name="CURRENCY" value="EUR">
<input type="hidden" name="AUTO_SETTLE_FLAG" value="1">
<input type="hidden" name="HPP_VERSION" value="2">
<input type="hidden" name="MERCHANT_RESPONSE_URL" value="https://www.example.com/responseUrl">
<!-- Begin AVS Field -->
<input type="hidden" name="BILLING_CODE" value="50001|Flat 123">
<!-- End AVS Field -->
<input type="hidden" name="SHA1HASH" value="308bb8dfbbfcc67c28d602d988ab104c3b08d012">
<input type="submit" value="Click To Pay">
</form>The following additional fields will be returned in the HPP response. They indicate the outcome of the AVS check.
<!-- Additional Response Fields -->
[AVSPOSTCODERESULT=M,
AVSADDRESSRESULT=M]| Element/Field | Category | Format | Description |
|---|---|---|---|
| AVS Postcode Response | string | enum | The result of the Address Verification Service (AVS) check on the postcode and first line of the billing address: M - Matched N - Not Matched I - Problem with check U - Unable to check - Issuer not certified, for example P - Partial Match Available for US, CA and GB cardholders only. |
| AVS Address Response | string | enum | See AVS Postcode Response |
Follow the steps in this section to build the request security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulting string to the request.
In addition to SHA-1, you can also generate your hash using SHA-256. The resulting hash should be placed in the tag instead of the tag. For more information, contact our support team.
Build the request hash for the Fraud Filter and data submission request type.
"timestamp.merchantid.orderid.amount.currency.fraud_filter_mode"If you're also using Card Storage, the blueprint becomes:
"timestamp.merchantid.orderid.amount.currency.payer.paymentref.fraudfiltermode"Based on the POST example above our initial string will be:
"20200205184615.Merchant ID.N6qsk4kYRZihmPrTXWYS6g.1001.EUR.PASSIVE"You'll need to concatenate this with your Shared Secret, for example:
"28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a"Follow the steps in this section to build the response security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulting string to the request.
Check the response hash for the Fraud Filter and data submission request type.
"timestamp.merchantid.orderid.result.message.pasref.authcode"So, based on the above example, the initial string to check the hash of the response will be:
"20200205184615.Merchant ID.N6qsk4kYRZihmPrTXWYS6g.00.[ test system ] Authorised.14631546336115597.12345"You'll need to concatenate this with your Shared Secret:
"28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a"We create the hash in the same way on our side and send it back. To confirm that a response hasn't been tampered with, compare what you've generated with what was returned in the sha1hash element.