Hosted Page Payment Features
This feature has two subfeatuers: the Payment and Pre-Authorization.
Use the Request URL and the Request Body Fields to perform a request for those subfeatures, then put in place your Receipt URL so the gateway can use the Response Body Fields to send the transaction's receipt.
Payment and Pre-Authorization
These features enables you to perform a Payment transaction or a Pre-authorization transaction, using a hosted page at the Payment Gateway.
This page is built to allow merchants to easily integrate with the system for processing one-off payments.
Using this solution, the Card Holders are redirected to the Gateway's payment page once they have made the decision to buy something at the Merchant's solution. All payment details are collected by Gateway's payment page to be sent to the Acquirer's Server once the submit button is pressed. The payment is then processed by Gateway and the Card Holder is redirected to the Merchant's Receipt page.
The above is accomplished by means of a simple HTML form post with a number of defined form fields, as you will see at the following subsections.
Both requests (Payment and Pre-auth) have the same body, but different Request URLs to be used.
| TYPE | REQUEST URL |
|---|---|
| Payment (Authorization) | https://testpayments.isvpay.io/merchant/paymentpage |
| Pre-Authorization | https://testpayments.isvpay.io/merchant/preauthpage |
Notes and Details About the Request
ND001 - Hash Formation
The gerenal rule to build HASH field is given at the Special Fields and Parameters page. For this specific feature, you should use the following formats:
When using a Single Currency Terminal, the string to generate the HASH field is going to formed using:
TERMINALID:ORDERID:AMOUNT:DATETIME:RECEIPTPAGEURL:VALIDATIONURL:SECRET
When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:RECEIPTPAGEURL:VALIDATIONURL:SECRET
ND002 - Hosted Page in an iFrame
It is also possible to process transactions using an iFrame rather than a full redirect. All the same fields are required as the standard full redirect integration. However, the implementation for the iFrame is slightly different. There are two methods of implementing it on an iFrame:
- 1. Build and submit the form as with standard integration, but within the iFrame.
- 2. Build the POST query string within the main page and then create an iFrame with the string as it's SRC value.
In either case, the following extra parameter should also be included at the request body:
| FIELD | REQUIRED | VALUE | DESCRIPTION |
|---|---|---|---|
| INIFRAME | YES | Y | Ensures that all redirects performed by our system do not break out of the iFrame. |
ND003 - Secure Card Registration by Payment Request
It is also possible to take advantage of a Payment Request to register a Secure Card. In this case, the following extra parameter should also be included at the request body:
| FIELD | REQUIRED | DESCRIPTION |
|---|---|---|
| SECURECARDMERCHANTREF | Y | Unique Reference assigned by the merchant site/software to identify the stored card details. Its length is limited to 48 characters. |
ND004 - Level 2 Data Validation
These fields are associate with of the Transaction`s Level 2 Enhanced Data. To be used, it's necessary that your terminal has the enhanced data enabled and set to LEVEL 2 or LEVEL 3. All of its fields, except for SHIPPING_ADDRESS2, are necessary if you want to have a better chance to qualify for Level 2 with your acquirer, but no field is actually mandatory.
This feature is only available for specific acquirers (contact our support team for more details).
ND005 - Multi Language Support
Depending on your customer's browser definitions and if there's a language template defined for his/ her language priority, the Payment Gateway is going to send the payment receipt translated. If the language is not supported by the gateway, the receipt is going to be sent using the gateway's language.
Examples for a Request
- Scenario: Minimum request, with only mandatory data.
- Terminal Currency Type: Single Currency Terminal.
- Terminal Secret: x4n35c32RT.
<html> <body> <form action="https://testpayments.isvpay.io/merchant/paymentpage" method="post"> <input type="hidden" name="TERMINALID" value="6491002" /> <input type="hidden" name="ORDERID" value="3281" /> <input type="hidden" name="CURRENCY" value="EUR" /> <input type="hidden" name="AMOUNT" value="10.00" /> <input type="hidden" name="DATETIME" value="15-3-2006:10:43:01:673" /> <input type="hidden" name="HASH" value="56083f2c6aa3d233dade436b1308805a" /> <input type="submit" value="Pay Now" /> </form> </body> </html>
- Scenario: Minimum request, with only mandatory data.
- Terminal Currency Type: Multi Currency Terminal.
- Transaction Processing Currency: EUR.
- Terminal Secret: x4n35c32RT.
<html> <body> <form action="https://testpayments.isvpay.io/merchant/paymentpage" method="post"> <input type="hidden" name="TERMINALID" value="6491002" /> <input type="hidden" name="ORDERID" value="3281" /> <input type="hidden" name="CURRENCY" value="EUR" /> <input type="hidden" name="AMOUNT" value="10.00" /> <input type="hidden" name="DATETIME" value="15-3-2006:10:43:01:673" /> <input type="hidden" name="HASH" value="e19685ec07de954398e971d237654e71" /> <input type="submit" value="Pay Now" /> </form> </body> </html>
REMEMBER to change the Terminal Id and Terminal Secret for valid values. Verify the Integration Docs for viable examples or contact our support team.
Response Body Fields
Remember that, when using the HPP integration method, the Payment Gateway is going to use the Receipt URL, configured at the Terminal or sent on request, to perform another request, but this time, as the response for the transaction processed by the Terminal. The response body field will be:
Filter:
| FIELD | DESCRIPTION |
|---|---|
| ORDERID | Same as informed at the transaction's request. |
| APPROVALCODE | A six digit AuthCode. |
| RESPONSECODE | A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively). E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay). D: (DECLINED). R: (REFERRED, also considered as PICKUP). C: (PICKUP, also known as Referral A or Referral B). For more details, visit Transaction Responses. |
| RESPONSETEXT | The text of the authorization. |
| DATETIME | The time of the transaction created by the bank. Format: YYYY-MM-DDTHH:MM:SS. |
| AVSRESPONSE | The result of the AVS check. Check Transaction Responses. |
| CVVRESPONSE | The result of the CVV check. See Appendix A for more information. |
| UNIQUEREF | Generated reference that should be stored for tracking and remote XML refunding. |
| Same as informed at the transaction's request. Returned if informed on request. | |
| PHONE | Same as informed at the transaction's request. Returned if informed on request. |
| COUNTRY | Same as informed at the transaction's request. Returned if informed on request. |
| CARDNUMBER | The card number (obfuscated) that was used for the transaction. |
| HASH | A HASH code formed by part of the response fields. The formation rule is given at the ND001 - Hash Formation, in the next section. |
| FRAUDREVIEWSTATUS | Values can be: PASS, REVIEW or REJECT. Consider the notes ND002 and ND003, in the next section. |
| FRAUDREVIEWRISKRATING | Values can be: HIGH, MEDIUM, LOW, NEUTRAL or TRUST. \\Consider the note ND002, in the next section. |
| FRAUDREVIEWSCORE | Number value, between -100 (highest risk) and +100 (lowest risk).\\Consider the note ND002, in the next section. |
| FRAUDREVIEWREASONCODE | Empty String, or a list of comma separated reasons of why this transaction is a risk. \\Consider the note ND002, in the next section. |
| CUSTOMFIELD | Same as informed at the transaction's request. Returns all custom fields informed on request. |
| OTHERFIELD | Same as informed at the transaction's request. Returns all additional fields informed on request. |
| BRANDTXIDENTIFIER | Same as informed at the transaction's request. Returned if informed on request |
| STOREDCREDENTIALUSE | Same as informed at the transaction's request. Returned if informed on request |
| STOREDCREDENTIALTXTYPE | Same as informed at the transaction's request. Returned if informed on request |
| CARDTYPE | Card Type used for the transaction. For more details on this, visit Special Fields and Parameters - Card Types. |
Notes and Details on the Response
ND001 - Hash Formation
The gerenal rule to build HASH field is given at the Special Fields and Parameters page, under the Special Fields and Parameters section.For this specific feature, you should use the following formats:
- Common case:
TERMINALID:ORDERID:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
- When the original request also requested the registering of a Secure Card:
TERMINALID:ORDERID:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET:MERCHANTREF:CARDREFERENCE:CARDTYPE:CARDNUMBER:CARDEXPIRY
When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:
- Common case:
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
- When the original request also requested the registering of a Secure Card:
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET:MERCHANTREF:CARDREFERENCE:CARDTYPE:CARDNUMBER:CARDEXPIRY
ND002 - Sentinel Defence Enabling
Sentinel Defence must be enabled for your Gateway and on the Terminal used for processing the transaction request.
ND003 - Sentinel Defence REVIEW status
If a transaction is returned with “FRAUDREVIEWSTATUS” as “REVIEW”, this transaction can be changed manually, using the new report feature on %Selfcare System, or using the transaction update XML gateway service, to “APPROVE” or “REJECT” the transaction. Transactions with this status are not going to be settled until the transaction status is changed. See the XML Gateway method for more details, more specifically, its Transaction Update feature, to change the transaction returned as “REVIEW” to “REJECT” or “APPROVE”.
ND004 - Secure Card Registration by Payment Request
When the SECURECARDMERCHANTREF field is sent on request, the Payment Gateway understands that you desire to create a Secure Card from the card data used for the transaction. In this case, the following extra parameter are going to be added to the response body:
| FIELD | DESCRIPTION |
|---|---|
| ISSTORED | Values can be: true or false. |
| SCERROR | Description of storage error if ISSTORED is “false” . |
| MERCHANTREF | Original SECURECARDMERCHANTREF provided by the Merchant on request. |
| CARDREFERENCE | Generated card reference. |
| CARDEXPIRY | Expiry date of the card. |
General Constraints and Rules Related to the Feature
Filter:
| CONSTRAINT | DESCRIPTION |
|---|---|
| C001 | The hosted Pre-Auth page allows for pre-authorization where the merchant account allows such requests. |
| C002 | Pre-auth transactions don't have the concept of Auto Ready, so to go into the READY state, they need to be completed using System or via an XML Completion request before they will be settled. |
| C003 | The final amount of a pre-auth transaction can be adjusted on completion. |