====== Accepting Payments & Pre-Auths ====== ~~TOC~~ %CompanyName-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. ^ **TYPE** ^ **SANDBOX URL** ^ | Payment | ''%URLTestPayments'' | | Pre-Authorization | ''%URLPreAuth'' | ===== Request ===== ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | TERMINALID | Y | ^{string ''[ 1 .. 50 ] characters''} \\ The terminal number assigned by %CompanyName. | | ORDERID | Y | ^{string ''[ 1 .. 24 ] characters''} \\ A unique identifier for the order assigned by the merchant. | | CURRENCY \\ ^{See notes: [[hpp_payment_features#ND008 - International payments|ND008]]} | Y | ^{string ''3-char ISO 4217 code''} \\ The currency of the transaction. | | AMOUNT | Y | ^{number ''> 0''} \\ The total amount to be authorized. | | DATETIME | Y | ^{string ''DD-MM-YYYY:HH:MM:SS:SSS''} \\ The transaction date and time. | | HASH \\ ^{See notes: [[hpp_payment_features#ND001 - Hash generation|ND001]]} | Y | ^{string ''[ 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 \\ ''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: [[hpp_payment_features#ND0012 - Cardholder email field|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 \\ This is the webhook that %CompanyName 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 \\ If the feature is enabled on your terminal, %CompanyName will use this webhook to perform background validation. If provided, it will overwrite the default **Background Validation URL**. Check out the **[[hosted_pages:hpp_background_validation|Background Validation]]** guide. | | TERMINALTYPE | N | ^number \\ ''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 \\ ''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: [[hpp_payment_features#ND004 - Address Verification System|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: [[hpp_payment_features#ND004 - Address Verification System|ND004]] | [[hpp_payment_features#ND005 - MaxMind MinFraud|ND005]]} | N | ^{string ''[ 1 .. 50 ] characters''} \\ The postal code of the billing address. | | CITY \\ ^{See notes: [[hpp_payment_features#ND004 - Address Verification System|ND004]] | [[hpp_payment_features#ND005 - MaxMind MinFraud|ND005]]} | N | ^{string ''[ 1 .. 128 ] characters''} \\ The city of the billing address. | | REGION \\ ^{See notes: [[hpp_payment_features#ND005 - MaxMind MinFraud|ND005]]} | N | ^{string ''[ 1 .. 128 ] characters''} \\ The region of the billing address. | | COUNTRY \\ ^{See notes: [[hpp_payment_features#ND005 - MaxMind MinFraud|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 **[[selfcare:api_specification:special_fields_and_parameters|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 \\ ''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 \\ ''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 \\ ''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 **[[selfcare:api_specification:special_fields_and_parameters|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: - Build and submit the form as with standard integration, but within the iFrame. - 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'' \\ ==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. \\ %CompanyName offers this service free of charge and it can be enabled in the terminal setup section of our Selfcare System. Check out more at **[[selfcare:api_specification:special_fields_and_parameters#the_maxmind_minfraud_fields|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, %CompanyName 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 %CompanyName - 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 ''>= 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. | {gateway=nuvei}{gateway=worldnet} \\ ==ND010 - Enhanced Data - Level 3== Add Level 3 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 and at least one line item in order to have a better chance to qualify for the lower Level 3 fees with your bank. \\ \\ To include line items, you need to replace the ''N'' with a sequential count identifier, e.g., ''LINE_ITEM_1_PRODUCT_CODE'', ''LINE_ITEM_1_TOTAL_AMOUNT'' and so on. ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | TOTAL_DISCOUNT_AMOUNT | N | ^{number ''>= 0''} \\ Total discount amount applied to the sale. | | TOTAL_FREIGHT_AMOUNT | N | ^{number ''>= 0''} \\ Total freight amount applied to the sale. | | TOTAL_DUTY_AMOUNT | N | ^{number ''>= 0''} \\ Total duty amount applied to the sale. | | LINE_ITEM_''N''_PRODUCT_CODE | N | ^{string ''[ 1 .. 45 ] characters''} \\ This is the merchant’s identifier for the product, also known as Universal Product code (UPC). | | LINE_ITEM_''N''_COMMODITY_CODE | N | ^{string ''[ 1 .. 45 ] characters''} \\ Item's commodidy code, defined for trade tariff. Widely used by corporate purchasing organizations to segment and manage their total spend across diverse product lines. | | LINE_ITEM_''N''_DESCRIPTION | N | ^{string ''[ 1 .. 250 ] characters''} \\ This is the merchant’s description for the product. | | LINE_ITEM_''N''_QUANTITY | N | ^{number ''> 0''} \\ Quantity of the specific item for the sale. | | LINE_ITEM_''N''_UNIT_OF_MEASURE| N | ^{string ''[ 1 .. 45 ] characters''} \\ Measure unit used for this specific item type to sell it in parts, units or sets.| | LINE_ITEM_''N''_UNIT_PRICE | N | ^{number ''> 0''} \\ Unit price applied for that specific type of item and measure unit, within the sale. | | LINE_ITEM_''N''_DISCOUNT_RATE | N | ^{number ''[ 0 .. 100 ]''} \\ A % of discount applied to the item's total amount **before** taxes. | | LINE_ITEM_''N''_TAX_RATE | N | ^{number ''[ 0 .. 100 ]''} \\ A % of tax applied to the item's total amount **after** discounts. | | LINE_ITEM_''N''_TOTAL_AMOUNT | N | ^{number ''> 0''} \\ The item's total amount ''quantity * unit price'' after discounts and taxes. | {/gateway} {gateway=worldnet} \\ ==ND011 - Convenience Fee - Line Items== Add Convenience Fee Line Items to your transactions by including the following extra fields in the request. \\ Note that your terminal must have Convenience Fee enabled, otherwise these fields will just be ignored. \\ \\ To include line items, you need to replace the N with a sequential count identifier, e.g., LINE_ITEM_N_QUANTITY, LINE_ITEM_N_UNIT_PRICE and so on. ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | LINE_ITEM_N_QUANTITY | N | ^{number > ''> 0''} \\ Quantity of the specific item for the sale. | | LINE_ITEM_N_UNIT_PRICE | N | ^{number > ''> 0''} \\ Unit price applied for that specific type of item and measure unit, within the sale. | {/gateway} \\ ==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: * **Hidden** - the gateway accepts the field, if sent, and adds it to the transaction, but does not show it to the customer. * **Optional** - an optional e-mail field is displayed to the cardholder. If you send the ''EMAIL'' parameter in the request, we'll use its value to pre-populate the field. * **Mandatory** - a required e-mail field is displayed to the cardholder. If you send the ''EMAIL'' parameter in the request, we'll use its value to pre-populate the field. ==== Request sample ==== * **Scenario**: Minimum request containing only mandatory data. * **Terminal Secret**: x4n35c32RT.

\\ ===== 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: ^ **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 \\ ''A'': Approval \\ ''E'': Accepted (China Union Pay only) \\ ''D'': Declined \\ ''R'': Referral \\ ''C'': Pick Up \\ For more details, visit **[[selfcare:integration_docs:transaction_responses|Transaction Responses]]**. | | RESPONSETEXT | ^{string ''[ 0 .. 48 ] characters''} \\ A brief description sent by the processor about the transaction result. | | DATETIME | ^{string ''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 **[[merchant:existing_merchant:other_information:transaction_responses|Transaction Responses]]** for a full list of AVS response codes. | | CVVRESPONSE | ^{string ''1 character''} \\ The result of the CVV check. See **[[merchant:existing_merchant:other_information:transaction_responses|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 **[[selfcare:api_specification:special_fields_and_parameters#the_card_types|Special Fields and Parameters - Card Types]]**. | | HASH \\ ^{See notes: [[hpp_payment_features#ND001 - Hash validation|ND001]]} | ^{string ''[ 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 \\ ON - The user accepted the convenience terms & conditions | | CONVENIENCE_FEE | ^{number ''> 0''} \\ A service fee charged on the transaction | | SURCHARGE_FEE | ^{number ''> 0''} \\ Surcharge amount. This field will be returned whenever a surcharge fee is applied to the transaction. | | SURCHARGE_PERCENT | ^{number ''[ 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 %CompanyName. See how to decode and validate a hash string at **[[selfcare:api_specification:special_fields_and_parameters|Special Fields and Parameters]]**. For this specific feature, you should expect one of the following formats: * __For single currency terminals__: /** * 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 \\ * __For multi-currency terminals__: /** * 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 %CompanyName, this is the token that represents the card details. | | CARDEXPIRY | ^{string ''MMYY''} \\ Expiry date of the card. | {gateway=nuvei} \\ ==ND003 - Sentinel Defend== See below the fields returned in the response for transactions processed by terminals with sentinel defend enabled: ^ **FIELD** ^ **DESCRIPTION** ^ | FRAUDREVIEWSTATUS | ^string \\ ''PASS'', ''REVIEW'', ''REJECT'' | | FRAUDREVIEWRISKRATING | ^string \\ ''HIGH'', ''MEDIUM'', ''LOW'', ''NEUTRAL'', ''TRUST'' | | FRAUDREVIEWSCORE | ^{number ''[ -100 .. 100 ] characters''} \\ Transaction's fraud score assigned by the sentinel defend service with ''-100'' being the highest risk and ''100'' representing the lowest risk of fraud. | | FRAUDREVIEWREASONCODE | ^string \\ If the transaction is considered to be high risk, a list of comma separated reasons that explain the risk of fraud is returned. | Transactions with a ''REVIEW'' status have to be either approved or rejected manually, this can be done by using the new report feature on the Selfcare System or our REST API. {/gateway} \\ ==== General constraints and rules ==== ^ **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. | \\ \\