Mandatory & Optional Fields
After your customers have decided how to pay, you present a corresponding HTML page with a form to enter the payment data as well as hidden parameters with additional transaction information. In addition to the mandatory fields, your form needs to contain also additional optional fields (part of them can be hidden) depending on a specific functionality or feature you wish to expose to your customers.
Mandatory Fields
Depending on the transaction type, the following form fields must be present in the form submitted
to the Gateway. Depending on the transaction type, the following form fields must be present in the form being submitted to the Gateway (X = mandatory field).
| Field Name | Description & Format | Sale | Preauth | Postauth | Payerauth |
|---|---|---|---|---|---|
txntype | The field represents a transaction type. Available values: 'sale’, 'preauth’, 'postauth’, or ‘payer_auth’ | X | X | X | X |
timezone | Time zone of the transaction in Area/Location format, e.g. Africa/Johannesburg America/New_York America/Sao_Paulo Asia/Calcutta Australia/Sydney Europe/Amsterdam Europe/Berlin Europe/Dublin Europe/London | X | X | X | X |
txndatetime | Exact transaction date and time; in the format "YYYY:MM:DD-hh:mm:ss" | X | X | X | X |
hash_algorithm | This is to indicate the algorithm that you use for hash calculation. Available values are: • HMACSHA256 • HMACSHA384 • HMACSHA512 Only one algorithm value should be used. | X | X | X | X |
hashExtended | The extended hash to be calculated using all non-empty Gateway specified request parameters in ascending order of the parameter names, where the upper-case characters come before the lower case (based on ASCII value) and the shared secret must be used as the secret key for calculating the hash value. | X | X | X | X |
storename | Represents unique identification of your account in our Gateway system. | X | X | X | X |
chargetotal | This is the total amount of the transaction using a dot or comma as decimal separator, e. g. 12.34 for an amount of 12 Euro and 34 Cent. Group separators like 1,000.01 / 1.000,01 are not allowed. | X | X | X | X |
checkoutoption | Set the value for this parameter to ‘combinedpage’ for a standard hosted payment page integration | X | X | X | |
currency | Represents the numeric ISO code of the transaction currency, e.g. 978 for EUR. | X | X | X | X |
oid | Order ID represents transaction identification number, must be unique for all primary transactions, if not provided in "sale", "preauth" or "payerAuth" request, the Gateway populates the parameter automatically. | X | |||
ipgTransactionId | Unique transaction identifier, generated by the Gateway in the response message for primary transactions; to be provided as a reference for subsequent transactions . | X | |||
merchantTransactionId | Optional parameter to be submitted if needed for your future reference; can be used as a reference for subsequent transactions. | X |
The transaction types ‘preauth’ and ‘postauth’ only apply to the payment methods credit card or PayPal.
The transaction type ‘payer_auth’ is only required if you want to split the 3-D Secure authentication process from the payment transaction (authorization) process.
Optional Fields
| Field Name | Description & Format |
|---|---|
cardFunction | Indicates the card function in case of combo cards which provide both credit and debit functionality. Can be set to 'credit' or 'debit'. |
comments | Can be utilised for any comments related to the transaction. |
customerid | Represents your customer identification number. Note: For Direct Debit transaction maximum allowed length is 32 characters. For iDeal transactions the customer ID will be displayed on client's bank account statement, if provided in the message. |
dccInquiryId | Inquiry ID for a Dynamic Pricing request, it is used to send the Inquiry ID you have obtained via a Web Service API call (‘RequestMerchantRateForDynamicPricing’). This value will be used to retrieve the currency conversion information (exchange rate, converted amount) for this transaction. |
dccSkipOffer | If the cardholder declines the currency conversion offer within your environment, the request parameter ‘dccSkipOffer’ can be set to ‘true’ so that the hosted consumer dialogue will automatically be skipped. |
dynamicMerchantName | The name of the merchant to be displayed on the cardholder’s statement. The length of this field should not exceed 25 characters. If you want to use this field, please contact your local support team to verify if this feature is supported in your country. |
hideOrderDetails | Set this parameter to ‘true’ when you want to hide (remove) the ‘Your Order' box from our hosted payment page. |
highRiskPurchaseIndicator | This optional parameter needs to be set to ‘true’, for transactions handling a cryptocurrency and initiated from a MCC 6051 (Quasi Cash—Merchant) store; or for transactions handling high risk securities initiated from the store with MCC 6211 (Securities—Brokers/ Dealers). |
invoicenumber | This field allows you to transmit any value, e.g. an invoice number or class of goods and it is limited to max 48 characters. |
item1 up to item999 | Line items are regular key-value parameters (URLencoded), where: • the name is a combination of the keyword item and a number, where the number indicates the list position e.g.: item1 • the value is represented by a semicolon-separated list of values, where the position indicates the meaning of the list item property e.g.: <1>;<2>;<3>;<4>;<5>;<6>;<7> The ‘item1’ to ‘item999’ parameters allow you to send basket information in the following format: `id;description;quantity;item_total_price;sub_total;vat_tax;shipping;local_tax;category;detailed_category |
language | This parameter can be used to override the default payment page language configured for your store. Currently available values can be found in References section: Languages |
mandateDate | Represents the date of the original mandate and is mandatory for recurring Direct Debit transactions. The date needs to be submitted in 'YYYYMMDD' format. |
mandateReference | Represents a mandate reference for Direct Debit payments. It is required to keep the Mandate Reference unambiguous. |
mandateType | Represents a type of Direct Debit transactions that are based on mandates for recurring collections. Available values: 'single' - for a single (one-off) debit collections (default value) 'firstCollection' - for initial debit collection 'recurringCollection' - for subsequent recurring debit collection; to be submitted together with 'mandateReference' field 'finalCollection' - for the last recurring debit transaction in a serie |
mandateUrl | The field to be used for submitting a URL for SEPA Direct Debit mandate processed via Local Payments. Must be submitted together with mandateReference and mandateDate |
marketplaceForeignRetailerIndicator | This field indicates if a marketplace retailer performing domestic transaction is in a different country. Available values: 'F' – marketplace retailer is foreign 'blank' – marketplace retailer is domestic The parameter must be sent if a transaction is submitted by a marketplace retailer in APAC region. |
merchantTransactionId | Optional parameter to be submitted if needed for your future reference; can be used as a reference for cancelling / returning the primary order. |
numberOfInstallments | Represents the number of instalments for a 'Sale' transaction. |
installmentsInterest | Indicates if an Installment payment includes interest. Available values: 'true' 'false' This parameter is available only to certain distribution channels in Latin America. |
installmentDelayMonths | This field should be used in case the Installment payment should be delayed for several months; alphanumeric with available values <2;99> |
oid | This field allows you to assign a unique ID for your order. If you choose not to assign an order ID, the Gateway will automatically generate one for you. Only the following characters are allowed: A-Z, a-z, 0-9, "-" For Direct Debit transactions, a maximum of 78 characters can be submitted. |
parentUri | If you plan to embed our hosted payment page inside an iFrame you must use this parameter, with the maximum length of 2048 characters, to specify an URL of a page, where the hosted payment page will be embedded. However, note that we do not recommend using the hosted payment forms inside an iFrame since some Internet browsers do not allow cookies to be sent to the 3rd party hosts, moreover some features (e.g.: 3-D Secure authentications) and some Alternative Payment methods that involve redirections to the 3rd party services (e.g.: iDEAL or PayPal) do not allow displaying their screens within an iFrame. |
partialApproval | The partial approval feature is particularly useful when the transaction amount exceeds the available funds on the customers card. This feature will allow an approval of the available amount to pay for a portion of the transaction, then the remainder can be paid using another payment method. If you are eligible to use this feature, then you can use this parameter to indicate whether to allow partial approval or not. Valid values: • true • false (default) |
paymentMethod | If you prefer to select the payment method yourself, submit this parameter along with your 'Sale' or 'PreAuth' transaction. If you do not submit this parameter, the Gateway displays a drop-down menu to the customer to choose from the payment methods available for your shop. |
ponumber | This field serves to submit a Purchase Order Number; 50 characters max |
refer | This field describes who referred the customer to your store. |
referencedMerchantTransactionID | This field allows to reference to a merchantTransactionId of a transaction when performing a secondary transaction request, e.g. Return |
referencedSchemeTransactionId | Credentials on file (COF) specific parameter. This field represents the value of a schemeTransactionId that has been returned in the response of the initial transaction to provide a reference to the original transaction, which stored the credentials for the first time. |
responseFailURL | The URL where you wish to direct customers after a declined or unsuccessful transaction (your Sorry URL) |
responseSuccessURL | The URL where you wish to direct customers after a successful transaction (your Thank You URL) |
shipping | This parameter can be used to submit the shipping fee, in the same format as chargetotalIf you submit shipping, the parameters subtotal and vattaxhave to be submitted as well.The chargetotalmust be equal to subtotal +shipping + vattax |
trxOrigin | Represents the origin of a transaction. Available values are: ‘MAIL’ - for transactions where the payment details are captured manually and provided in written form the Card Code entry is not allowed ‘PHONE’ - for transactions where you have received the order over the phone and enter the payment details yourself the Card Code entry is required ‘ECI‘ - for standard usage in an eCommerce environment where your customer enters the payment details |
unscheduledCredentialOnFileType | Credentials on file (COF) specific parameter to flag transactions as unscheduled credential on file type. Available values are: FIRST - for initial transaction in a series CARDHOLDER_INITIATED - for an unscheduled transaction initiated by your cardholder MERCHANT_INITIATED - for an unscheduled transaction initiated by yourselves |
vattax | Represents Value Added Tax or other taxes, e.g.: GST in Australia. Sub total amount + shipping + tax = charge total |
Updated 5 months ago
