Hosted Payment Page: Payment

Hosted Payment Pages support two types of credit card transactions: Payments and Pre-Authorizations.

Use the Request URL and the Request Body Fields to perform a Payment or Pre-Authorization request, 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

Perform a Payment transaction or a Pre-authorization transaction, using a Hosted Payment Page.

Using this solution, cardholders are redirected to a hosted payment page once they have decided to make a purchase using the merchant's browser-based software application. All payment details are collected by hosted payment page and are then sent for authorization once the submit button is selected. The payment is then processed by Gateway and the cardholder is redirected to the Receipt page.

The above is accomplished by means of a simple HTML form post with a number of defined form fields, detailed in 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.nuvei.com/merchant/paymentpage
Pre-Authorization	https://testpayments.nuvei.com/merchant/preauthpage

Request Body Fields

Filter:

FIELD	REQUIRED	DESCRIPTION
TERMINALID	Y	A TerminalID provided by the merchant service provider.
ORDERID	Y	A unique identifier for the order created by the merchant. Maximum of 24 Characters.
CURRENCY	Y	Currency of the transaction. A 3 character code following the ISO 4217 Currency Code.
AMOUNT	Y	The amount of the transaction. A 2 digit decimal or an integer value for JPY amounts.
DATETIME	Y	Transaction date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	Y	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.
CARDHOLDERNAME	N	This will pre-populate the Cardholder Name field on the payment page. This will be editable on the payment page. It should be as displayed on the front of the card.
AUTOREADY	N	Values can be: Y or N. Automatically set the transaction to Ready in the batch. If not present, the terminal default will be used.
DESCRIPTION	N	A description of the transaction.
EMAIL	N	An email address to send a confirmation email to. Normally this is cardholder email address.
RECEIPTPAGEURL	N	This is the URL of the page on your site that will display the result of the transaction. If sent this will override the terminal setting in the SelfCare System (Merchant Portal).
VALIDATIONURL	N	This will overwrite the default Background Validation URL and will display an error if this feature is not enabled and sent. The next section's subfeature uses this URL (or the one configured at the Terminal) to send a request to validate the transaction. If sent this will override the terminal setting in the SelfCare System (Merchant Portal).
TERMINALTYPE	N	Defines how the transaction is to be processed. Values can be: 1: As Mail Order/Telephone Order. 2: eCommerce. Mail Order transactions can have a separate payment Page Layout.
TRANSACTIONTYPE	N	Values can be: 4: Normal Mail order/Telephone Oder trans (Mail Order for first Data Latvia). 7: Normal eCommerce trans. 9: Telephone Order (First Data Latvia only).
ADDRESS1	N	First line of address. This field will pre-populate the ADDRESS1 field on the Hosted Payment Page, if there is also a valid POSTCODE sent and AVS is enabled for the terminal. Handling of display is managed by the gateway and can be set to display (read only or editable) or to hidden on the page.
ADDRESS2	N	Second line of address. Same behavior as ADDRESS1.
POSTCODE	N	Post code for the address. If sent, then AVS data will be populated. Required for MaxMind MinFraud fraud scoring complementary service.
CITY	N	City for the address. Required for MaxMind MinFraud fraud scoring complementary service.
REGION	N	Region for the address. Required for MaxMind MinFraud fraud scoring complementary service.
COUNTRY	N	Country code for the address. Following the ISO 3166-1-alpha-2 Country Code. Required for MaxMind MinFraud fraud scoring complementary service.
PHONE	N	Customer phone number, to be stored against transaction. International format and numeric.
PAYMENTTYPE	N	Set to CUP_SECUREPAY in order to forward directly to China Union Pay.
CUSTOMER_REF_NUMBER	N	Text type field with max length of 48 characteres. This number is defined by the cardmember. It is entered by the merchant at the point of sale. Also, see Notes 4 and 5 below.
TAX_AMOUNT	N	Value type field, with max length of 13 algarisms. A value of zero is required in order to indicate tax exempt transactions. Also, see Notes 4 and 5 below.
SHIPPING_FULL_NAME	N	Text type field with max length of 50 characteres. See ND004 - Level II Data Validation for more details.
SHIPPING_ADDRESS1	N	Text type field with max length of 50 characteres. See ND004 - Level II Data Validation for more details.
SHIPPING_ADDRESS2	N	Text type field with max length of 50 characteres. Always optional regardless compulsory setting. See ND004 - Level II Data Validation for more details.
SHIPPING_CITY	N	Text type field, between 1 and 128 characteres. See ND004 - Level II Data Validation for more details.
SHIPPING_REGION	N	Text type field, between 1 and 128 characteres. See ND004 - Level II Data Validation for more details.
SHIPPING_POSTCODE	N	Text type field, between 1 and 50 characteres. See ND004 - Level II Data Validation for more details.
SHIPPING_COUNTRY	N	Text type field, with 2 characteres. ISO ALPHA-2 Country Code. Also, see Notes 4 and 5 below.
TOTAL_DISCOUNT_AMOUNT	N	Total discount amount provided to the sale. Max of 13 characters and 3 decimal points, depending on your terminal's currency. See ND006 for more details.
TOTAL_FREIGHT_AMOUNT	N	Total freight amount applied to the sale. Max of 13 characters and 3 decimal points, depending on your terminal's currency. See ND006 for more details.
TOTAL_DUTY_AMOUNT	N	Total discount amount applied to the sale. Max of 13 characters and 3 decimal points, depending on your terminal's currency. See ND006 for more details.
LINE_ITEM_'N'_PRODUCT_CODE	N	This is the merchant's identifier for the product. Also known as Universal Product Code (UPC). Subfield of a line item. You can add as many items as you see fit, using a sequential instead of 'N' to identify its fields. Its value can be up to 45 characters. See ND006 for more details.
LINE_ITEM_'N'_COMMODITY_CODE	N	Item's commodity code, defined for trade tariff. Widely used by corporate purchasing organizations to segment and manage their total spend across diverse product line . Defined at government or commercial aggrements level. Consult your Acquirer for more details. Subfield of a line item. You can add as many items as you see fit, using a sequential instead of 'N' to identify its fields. Its value can be up to 45 characters. See ND006 - Level 3 Data Validation.
LINE_ITEM_'N'_DESCRIPTION	N	This is the merchant's description for the product. Subfield of a line item. You can add as many items as you see fit, using a sequential instead of 'N' to identify its fields. Its value can be up to 250 characters. See ND006 for more details.
LINE_ITEM_'N'_QUANTITY	N	Quantity of the specific item for the sale. See ND006 for more details.
LINE_ITEM_'N'_UNIT_OF_MEASURE	N	Measure unit used for this specific type to sell it in parts, units, or sets. Subfield of a line item. You can add as many items as you see fit, using a sequential instead of 'N' to identify its fields. Its value can be up to 45 characters. See ND006 for more details.
LINE_ITEM_'N'_UNIT_PRICE	N	Unit price applied for that specific type of item and measure unity, within the sale. Max of 13 characters and 3 decimal points, depending on your terminal's currency. See ND006 for more details.
LINE_ITEM_'N'_DISCOUNT_RATE	N	A % of discount applied to the item total (quantity x unit price) before taxes. Max of 100%. See ND006 for more details.
LINE_ITEM_'N'_TAX_RATE	N	A % of tax applied to the item total (quantity x unit price) after discounts. Max of 100%. See ND006 for more details.
LINE_ITEM_'N'_TOTAL_AMOUNT	N	Final item value based on total (quantity x unit price) after discount and tax applied. Max of 13 characters and 3 decimal points, depending on your terminal's currency. See ND006 for more details.
CUSTOMFIELD	N	Any of the available Custom Fields for the Terminal. If there are Custom Fields enabled for the specific Terminal in use, the Hosted Page will only display the fields that were not included in the request. The Hosted Page will conceal the included fields and will automatically populate them with the values supplied in the request. These values will be stored and utilized by the Payment Gateway for the requests sent to the Receipt URL and the Validation URL. To understand more visit the section regarding Special Fields and Parameters.
ORIGNALBRANDTXIDENTIFIER	N	String, max length is 64 - Merchant sends the transaction identifier received from acquirer See note ND008 - Stored Credential use field behavior and settings.
STOREDCREDENTIALUSE	N	UNSCHEDULED, INSTALLMENT or RECURRRING. See note ND008 - Stored Credential use field behavior and settings.
STOREDCREDENTIALTXTYPE	N	FIRST_TXN, SUBSEQUENT_MERCHANT_INITIATED_TXN or SUBSEQUENT_CARDHOLDER_INITIATED_TXN. See note ND008 - Stored Credential use field behavior and settings.
BYPASS_SURCHARGE	N	Send a value of 'true' to identify that surcharge has not been applied to this payment. Only applicable if surcharging is enabled for the terminal.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. 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 (token) Registration by Payment Request

It is also possible to take advantage of a Payment Request to register a Secure Card (token). 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 II Data Validation

This field is associate with the feature “Level II Data”, and to be used is necessary to set the “Allow Level II Data” option, on a Processing Terminal “Features” section. And this feature is only available for specific acquirers (contact our support team for more details). All the fields associated with the feature “Level II Data”, except for SHIPPING_ADDRESS2, are mandatory when the “Level II Data Compulsory” is checked in the Processing Terminal “Features” section.

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.

ND008 - Stored Credential use field behavior and settings

This feature is currently available to TSYS Saratoga terminals. The COF tags are required for the following usage:

• Processing transaction in clear card but token vaulted externally (outside the Gateway).

The fields will have the following behavior: Hidden - the gateway accepts the fields, if sent, and adds them to the transaction, but does not show it for the customer.

To provide a transaction with COF, your request needs to add the Credential on File component and its fields, as described below.

FIELD	REQUIRED	DESCRIPTION
ORIGINALBRANDTXIDENTIFIER	N	String, max length is 64, Merchant sends the transaction identifier if received from acquirer.
STOREDCREDENTIALTXTYPE	N	Possible values: FIRST_TXN_SUBSEQUENT_MERCHANT_INITIATED_TXN or SUBSEQUENT_CARDHOLDER_INITITATED_TXN
STOREDCREDENTIALUSE	N	Possible values: UNSCHEDULED, INSTALLMENT or RECURRING.

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.nuvei.com/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.nuvei.com/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 replace the TERMINALID and Terminal Secret with valid values.

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 what was provided in 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.
EMAIL	Same as what was provided in the transaction's request. Returned if provided on request.
PHONE	Same as what was provided in the transaction's request. Returned if provided on request.
COUNTRY	Same as what was provided in the transaction's request. Returned if provided 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	No longer supported.
FRAUDREVIEWRISKRATING	No longer supported.
FRAUDREVIEWSCORE	No longer supported.
FRAUDREVIEWREASONCODE	No longer supported.
CUSTOMFIELD	Same as what was provided in the transaction's request. Returns all custom fields provided on request.
OTHERFIELD	Same as what was provided in the transaction's request. Returns all additional fields provided on request.
BRANDTXIDENTIFIER	Same as what was provided in the transaction's request. Returned if provided on request.
STOREDCREDENTIALUSE	Same as what was provided in the transaction's request. Returned if provided on request.
STOREDCREDENTIALTXTYPE	Same as what was provided in the transaction's request. Returned if provided on request.

Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given at the Special Fields and Parameters page, under the Hash Parameter 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 (token):

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 (token):

TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET:MERCHANTREF:CARDREFERENCE:CARDTYPE:CARDNUMBER:CARDEXPIRY

ND004 - Secure Card (token) Registration by Payment Request

When the SECURECARDMERCHANTREF field is sent on request, the Payment Gateway understands that you desire to create a Secure Card (token) 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.
CARDTYPE	Card Type used for the transaction. For more details on this, visit Special Fields and Parameters - Card Types.
CARDEXPIRY	Expiry date of the card.

For more details on this feature, visit the Products - Secure Card section.

ND006 - Level 3 Data Validation

This field is associated with the Enhanced Data (Level II and Level III) feature. “Allow Enhanced Data (Level II and Level III)” must be enabled, with the “Transaction Data Level” option set as “Level III" on the Processing Terminal. Contact our Support Team to configure this option.

To provide a transaction with LEVEL III, your request needs to add the LEVEL_2_DATA (described before) and the LEVEL_3_DATA components and their fields. The LEVEL_3_DATA component fields are described below.

FIELD	REQUIRED	DESCRIPTION
SUMMARY	N	Subcomponent of Level 3. Agregates the sum of different values within the transaction.
TOTAL_DISCOUNT_AMOUNT	N	Subfield of SUMMARY. Represents the freight amount applied to the sale. Decimal value, allowing max of 13 digits within min value of 0.
TOTAL_DUTY_AMOUNT	N	Subfield of SUMMARY. Represents duty applied to the sale. Decimal value, allowing max of 13 digits with min value of 0.
LINE_ITEMS	N	Subcomponent of Level 3. List of all items in which the sale is broken down.
LINE_ITEM	N	Subfield of LINE_ITEMS. Holds all the details of a sale's item. You can add as much as necessary to express the breaking down of your sale.
COMMODITY_CODE	N	Subfield of LINE_ITEM. Item's commodity code, defined for trade tariff. Widely used by corporate purchasing organizations to segment and manage their total spend accross diverse product lines. Defined at government or commercail agreements level. Consult your Acquirer for more details.
PRODUCT_CODE	N	Subfield of LINE_ITEM. This is the merchant's identifier for the product, also known as Universal Product code (UPC).
DESCRIPTION	N	Subfield of LINE_ITEM. This is the merchant's description for the product.
QUANTITY	N	Subfield of LINE_ITEM. Quantity of the specific item for the sale.
UNIT_OF_MEASURE	N	Subfield of LINE_ITEM. Measure unit used for this specific item type to sell it in parts, units or sets.
UNIT_PRICE	N	Subfield of LINE_ITEM. Unit price applied for that specific type of item and measure unit, within the sale.
DISCOUNT_RATE	N	Subfield of LINE_ITEM. A % of discount applied to the item total (quantity x unit price) before taxes.
TAX_RATE	N	Subfield of LINE_ITEM. A % of tax applied to the item total (quantity x unit price) after discounts.
TOTAL_AMOUNT	N	Subfield of LINE_ITEM. Final item value based on total (quantity x unit price) after discount and tax applied.

Quick Example

<LEVEL_2_DATA>...</LEVEL_2_DATA>
<LEVEL_3_DATA>
     <SUMMARY>
          <TOTAL_DISCOUNT_AMOUNT>61.30</TOTAL_DISCOUNT_AMOUNT>
          <TOTAL_FREIGHT_AMOUNT>3.50</TOTAL_FREIGHT_AMOUNT>
          <TOTAL_DUTY_AMOUNT>11.50</TOTAL_DUTY_AMOUNT>
     </SUMMARY>
     <LINE_ITEMS>
          <!-- As many as necessary -->
          <LINE_ITEM>
               <COMMODITY_CODE>PDX001</COMMODITY_CODE>
               <PRODUCT_CODE>DSV1303.090.00001</PRODUCT_CODE>
               <DESCRIPTION>General services</DESCRIPTION>
               <QUANTITY>10</QUANTITY>
               <UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE>
               <UNIT_PRICE>105.50</UNIT_PRICE>
               <DISCOUNT_RATE>5.00</DISCOUNT_RATE>
               <TAX_RATE>12.50</TAX_RATE>
               <TOTAL_AMOUNT>1127.53</TOTAL_AMOUNT>
          </LINE_ITEM>
          <LINE_ITEM>
               <COMMODITY_CODE>PDX002</COMMODITY_CODE>
               <PRODUCT_CODE>DSV1302.090.00001</PRODUCT_CODE>
               <DESCRIPTION>General services</DESCRIPTION>
               <QUANTITY>2</QUANTITY>
               <UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE>
               <UNIT_PRICE>85.50</UNIT_PRICE>
               <DISCOUNT_RATE>5.00</DISCOUNT_RATE>
               <TAX_RATE>16.00</TAX_RATE>
               <TOTAL_AMOUNT>188.44</TOTAL_AMOUNT>
          </LINE_ITEM>
     </LINE_ITEMS>
</LEVEL_3_DATA>

DON'T FORGET
If you are using LEVEL_3_DATA compononent, also add to your request the LEVEL_2_DATA 2 component to attempt a full qualification for enhanced data.

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 SelfCare 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.