Table of Contents

Accepting Payments & Pre-Auths

-hosted payment page enables you to create secure and fully customized payment forms that let you accept payments on your website.

This solution works across devices and doesn't require much development work, all you need to do is send us a POST request with a set of pre-defined fields.

The request body will be identical for payments and pre-auths, the distintion is made based on the request URL as you can see below.

TYPE SANDBOX URL
Payment
Pre-Authorization

Request

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y string [ 1 .. 50 ] characters
The terminal number assigned by .
ORDERID Y string [ 1 .. 24 ] characters
A unique identifier for the order assigned by the merchant.
CURRENCY
See notes: ND008 		Y string 3-char ISO 4217 code
The currency of the transaction.
AMOUNT Y number <double> > 0
The total amount to be authorized.
DATETIME Y string <date-time> DD-MM-YYYY:HH:MM:SS:SSS
The transaction date and time.
HASH
See notes: ND001 		Y string <SHA-512> [ 1 .. 128 ] characters
A HASH code formed by part of the request fields.
CARDHOLDERNAME N string [ 1 .. 50 ] characters
The cardholder's name as it appears on the card. If provided, it will be used to pre-populate the cardholder name field on the payment page.
AUTOREADY N string <enum>
Y - The gateway will automatically set the transaction to READY, making it eligible to be batched in the next settlement run.
N - Flags the transaction with a PENDING status meaning that the transaction won't be settled until the merchant marks it as ready.

If not provided, the terminal default will take place.
DESCRIPTION N string [ 1 .. 1024 ] characters
A brief description of the transaction.
EMAIL
See notes: ND0012 		N string [ 1 .. 128 ] characters
The cardholder email address.
If Email Cardholder Receipt feature is enabled on the terminal, we will use this address to delivery transaction receipts to your customer.
RECEIPTPAGEURL N string <URI>
This is the webhook that will use to send you the result of the transactions. If provided, this will override the terminal setting in the Selfcare System.
VALIDATIONURL N string <URI>
If the feature is enabled on your terminal, will use this webhook to perform background validation. If provided, it will overwrite the default Background Validation URL. Check out the Background Validation guide.
TERMINALTYPE N number <integer>
1 - As Mail Order/Telephone Order.
2 - eCommerce.
Defines how the transaction is to be processed. Mail Order transactions can have a separate payment Page Layout.
3 - Cardholder Present.
HPP has support for GENERIC_MSR or SRED_KEYED terminal devices.
TRANSACTIONTYPE N number <integer>
4 - Normal Mail order/Telephone Order trans (Mail Order for first Data Latvia).
5 - 3DS fully authenticated trans.
6 - 3DS attempted trans.
7 - Normal eCommerce trans.
9 - Telephone Order (First Data Latvia only).
ADDRESS1
See notes: ND004 		N string [ 1 .. 50 ] characters
The first line of the billing address.
ADDRESS2 N string [ 1 .. 50 ] characters
The second line of the billing address.
POSTCODE
See notes: ND004 | ND005 		N string [ 1 .. 50 ] characters
The postal code of the billing address.
CITY
See notes: ND004 | ND005 		N string [ 1 .. 128 ] characters
The city of the billing address.
REGION
See notes: ND005 		N string [ 1 .. 128 ] characters
The region of the billing address.
COUNTRY
See notes: ND005 		N string 2-char ISO 3166-1 code
The country of the billing address.
PHONE N string [ 5 .. 20 ] characters
The cardholder phone number. International numeric format.
PAYMENTTYPE N CUP_SECUREPAY - To forward the transaction directly to China Union Pay.
CUSTOMFIELD N You can send any of the custom fields configured on your terminal. Otherwise, they will be displayed as inputs, so that the cardholder can populate them. All custom fields will be stored along with the transaction details and echoed back to the Receipt URL. Check Special Fields and Parameters for more details.
OTHERFIELD N Any other fields sent in the request will be treated as metadata. They are not going to be stored, but they'll be echoed back to the Receipt URL. Note that this is subject to the max length of a HTTP GET request which we would conservatively recommend considering to be 2000 characters.
ORIGINALBRANDTXIDENTIFIER N string [ 1 .. 50 ] characters
Reference provided by the card scheme. Only relevant to merchants using a third-party vault for tokenization.
STOREDCREDENTIALUSE N string <enum>
UNSCHEDULED, INSTALLMENT, RECURRING
When cardholders authorize a merchant to store their card details, they must explicitly consent to how their credentials will be used in the future.
STOREDCREDENTIALTXTYPE N string <enum>
FIRST_TXN - The first payment where the customer is signing up for a series of subsequent payments.
SUBSEQUENT_CARDHOLDER_INITIATED_TXN - A subsequent payment initiated by the cardholder (CIT).
SUBSEQUENT_MERCHANT_INITIATED_TXN - A subsequent payment initiated by the merchant (MIT) on behalf of the cardholder.
CARDREFERENCE N string [ 12 .. 19 ] characters
Token reference of an existing Secure Tokens.
If provided, your customer won't be able to change the card details or use a different payment method on the hosted page.
BYPASS_SURCHARGE N boolean
true, false. 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.
PAYMENTOPTIONS N string <enum>
CARD
BANK_TRANSFER
CARD_AND_BANK_TRANSFER
Restricts payment options to either cards, bank transfer providers or both. Not providing a value is equivalent to the CARD_AND_BANK_TRANSFER option.

Request notes

ND001 - Hash generation

See how to generate a hash string at Special Fields and Parameters. For this specific feature, you should use one of the following formats:

  • For single currency terminals:
TERMINALID:ORDERID:AMOUNT:DATETIME:RECEIPTPAGEURL:VALIDATIONURL:SECRET
  • For multi-currency terminals:
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:RECEIPTPAGEURL:VALIDATIONURL:SECRET


ND002 - Hosted page in an iFrame

If you don't want the customer to leave your site you can implement the HPP within an iframe. There are two ways to do that:

  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.

Either way, the following extra parameter should also be included in the request:

FIELD REQUIRED DESCRIPTION
INIFRAME Y Y - Ensures that all redirects performed by our system do not break out of the iFrame.


ND003 - Storing card details

Give customers the option to store their card details during a payment. To display this option, you just need to include the field below in the request:

FIELD REQUIRED DESCRIPTION
SECURECARDMERCHANTREF Y string [ 1 .. 200 ] characters
Unique Reference assigned by the merchant to identify the stored card details.


ND004 - Address Verification System

Address Verification System (AVS) is a service provided by major credit card processors to enable merchants to authenticate ownership of a credit or debit card used by a customer.
It’s done as part of the authorization request where the bank checks the billing address provided by the cardholder against the billing address in its records.

The fields included in the verification process are:

  • ADDRESS1
  • POSTCODE
  • CITY

From your Selfcare account, you can enable the AVS feature and fully customize the way the address fields behave on the hosted page. For instance, it's possible to choose whether they should be required or optional as well as if they should be displayed to the cardholder or not.


ND005 - MaxMind MinFraud

MaxMind provides a score for each transaction between 0.01 and 100 (riskScore), effectively the percentage chance that it could be fraudulent.
offers this service free of charge and it can be enabled in the terminal setup section of our Selfcare System. Check out more at Special Fields and Parameters.

Your request must contain at least the following fields to trigger a MaxMind check:

  • CITY
  • REGION
  • COUNTRY


ND006 - Multi Language Support

Depending on your customer's browser definitions and if there's a language template defined for his/her language priority, 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.


ND007 - Stored Credential use field behavior and settings

This feature is currently available to TSYS Saratoga terminals and is configurable by customer support. These fields will only be used on a payment if you have Secure Tokens storage enabled. 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.


ND008 - International payments

If you want to be able to accept international payments, make sure your account has any type of multi-currency processing enabled.
The most common is DCC (Dynamic Currency Conversion), it is also the only form of multi-currency processing that adds extra steps to the cadholder experience.

When a customer is paying with a foreing card, a decision page - which is also hosted by - will be displayed where the customer has to decide whether he wants to pay in his home currency or in the terminal's base currency.


ND009 - Enhanced Data - Level 2

Add Level 2 data to your transactions by including the following extra fields in the request.
Note that your terminal must support and be enabled to process enhanced data, otherwise these fields will just be ignored.
Make sure to send as much information as possible in order to have a better chance to qualify for the lower Level 2 fees with your bank.

FIELD REQUIRED DESCRIPTION
CUSTOMER_REF_NUMBER N string [ 1 .. 48 ] characters
Sometimes referred to as customer code, it must be sent if provided by the cardholder.
TAX_AMOUNT N number <double> >= 0
Sales tax amount.
0 - Indicates that the transactions is exempt of tax.
SHIPPING_FULL_NAME N string [ 1 .. 50 ] characters
Shipping address - contact name.
SHIPPING_ADDRESS1 N string [ 1 .. 50 ] characters
Shipping address - first line.
SHIPPING_ADDRESS2 N string [ 1 .. 50 ] characters
Shipping address - second line.
SHIPPING_CITY N string [ 1 .. 128 ] characters
Shipping address - city.
SHIPPING_REGION N string [ 1 .. 128 ] characters
Shipping address - region.
SHIPPING_POSTCODE N string [ 1 .. 50 ] characters
Shipping address - postal code.
SHIPPING_COUNTRY N string 2-char ISO 3166-1 code
Shipping address - country.


ND0012 - Cardholder email field

This field is available for all terminals, but depending on the Hosted payment page email field setup terminal setting, it might have one of the following behaviors:

The email address will be mandatory for transactions with 3-D Secure Authentication.

Request sample

<html>
  <body>
    <form action="" 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-2023:10:43:01:673" />
       <input type="hidden" name="HASH" value="56083f2c6aa3d233dade436b1308805a" />
       <input type="submit" value="Pay Now" />
    </form>
  </body>
</html>


Remember to change the TERMINALID and SECRET for valid values. Ready to try? Sign up for a sandbox account.

Response

Assuming valid details were sent, the hosted page will be displayed to the cardholder and he'll be prompted to enter his card details. Once the payment is processed, the following parameters will be forwarded to the Receipt URL configured in your terminal:

Filter:

FIELD DESCRIPTION
ORDERID string [ 1 .. 24 ] characters
Echoed back from the request.
APPROVALCODE string [ 0 .. 48 ] characters
The authorization code assigned by the payment processor for approved transactions.
RESPONSECODE string <enum>
A: Approval
E: Accepted (China Union Pay only)
D: Declined
R: Referral
C: Pick Up
For more details, visit Transaction Responses.
RESPONSETEXT string [ 0 .. 48 ] characters
A brief description sent by the processor about the transaction result.
DATETIME string <date-time> DD-MM-YYYY:HH:MM:SS:SSS
The processing date and time of the transaction.
AVSRESPONSE string 1 character
The result of the AVS check. See Transaction Responses for a full list of AVS response codes.
CVVRESPONSE string 1 character
The result of the CVV check. See Transaction Responses for a full list of CVV response codes.
UNIQUEREF string 10 characters
Unique reference number assigned by the gateway that should be stored to be able to perform follow up operations, such as reversals and refunds.
EMAIL string [ 1 .. 128 ] characters
Echoed back from the request.
PHONE string [ 5 .. 20 ] characters
Echoed back from the request.
COUNTRY string 2-char ISO 3166-1 code
Echoed back from the request.
CARDNUMBER string [ 12 .. 19 ] characters
The card number masked as per PCI requirements.
CARDTYPE Card type used for the transaction.
For more details on this, visit Special Fields and Parameters - Card Types.
HASH
See notes: ND001 		string <SHA-512> [ 1 .. 128 ] characters
A HASH code formed by part of the response fields.
CUSTOMFIELD Echoed back from the request.
OTHERFIELD Echoed back from the request.
BRANDTXIDENTIFIER Echoed back from the request.
STOREDCREDENTIALUSE Echoed back from the request.
STOREDCREDENTIALTXTYPE Echoed back from the request.
ACCEPTTERMSANDCONDITIONS string <enum>
ON - The user accepted the convenience terms & conditions
CONVENIENCE_FEE number <double> > 0
A service fee charged on the transaction
SURCHARGE_FEE number <double> > 0
Surcharge amount. This field will be returned whenever a surcharge fee is applied to the transaction.
SURCHARGE_PERCENT number <double> [ 0 .. 100 ]
Surcharge percentage. This field will be returned whenever a surcharge fee is applied to the transaction.


Response notes

ND001 - Hash validation

A hash string is also included in the response, so that you can implement a verification logic to make sure it was sent by . See how to decode and validate a hash string at Special Fields and Parameters.

For this specific feature, you should expect one of the following formats: 

/**
 * The general case
 */
TERMINALID:ORDERID:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
 
/**
 * When a Secure Tokens was registered as part of the transaction
 */
TERMINALID:ORDERID:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET:MERCHANTREF:CARDREFERENCE:CARDTYPE:CARDNUMBER:CARDEXPIRY


/**
 * The general case
 */
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
 
/**
 * When a Secure Tokens was registered as part of the transaction
 */
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET:MERCHANTREF:CARDREFERENCE:CARDTYPE:CARDNUMBER:CARDEXPIRY


ND002 - Secure Token registration

By including the SECURECARDMERCHANTREF field in the request, you give customers the option to store their card details.
If a customer checks that option, the gateway automatically triggers a secure registration and adds the following extra parameters to the response:

FIELD DESCRIPTION
ISSTORED boolean
true, false
SCERROR If ISSTORED = false, check out this field for a brief description of the failure.
MERCHANTREF string [ 1 .. 200 ] characters
The same SECURECARDMERCHANTREF you sent in the request.
CARDREFERENCE string [ 12 .. 19 ] characters
The reference number assigned by , this is the token that represents the card details.
CARDEXPIRY string MMYY
Expiry date of the card.


General constraints and rules

Filter:

CONSTRAINT DESCRIPTION
C001 To use the hosted pre-auth page, your terminal must be enabled to process pre-auth transactions.
C002 Pre-authorizations require an extra step called completion or capture, this operation can be done using our Selfcare System or via our REST API.
If a pre-auth is not captured, it'll never settle and it'll expire after some time.
C003 The final amount of a pre-auth transaction can be adjusted on completion.