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 NameDescription & FormatSalePreauthPostauthPayerauth
txntypeThe field represents a transaction type. Available values:
'sale’, 'preauth’, 'postauth’, or ‘payer_auth’
XXXX
timezoneTime 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
XXXX
txndatetimeExact transaction date and time; in the format "YYYY:MM:DD-hh:mm:ss" XXXX
hash_algorithmThis is to indicate the algorithm that you use for hash calculation.
Available values are:
• HMACSHA256
• HMACSHA384
• HMACSHA512
Only one algorithm value should be used.
XXXX
hashExtendedThe 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. XXXX
storenameRepresents unique identification of your account in our Gateway system. XXXX
chargetotalThis 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.XXXX
checkoutoptionSet the value for this parameter to ‘combinedpage’ for a standard hosted payment page integrationXXX
currencyRepresents the numeric ISO code of the transaction currency, e.g. 978 for EUR.XXXX
oidOrder 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
ipgTransactionIdUnique transaction identifier, generated by the Gateway in the response message for primary transactions; to be provided as a reference for subsequent transactions .X
merchantTransactionIdOptional 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 NameDescription & Format
cardFunctionIndicates the card function in case of combo cards which provide both credit and debit functionality.
Can be set to 'credit' or 'debit'.
commentsCan be utilised for any comments related to the transaction.
customeridRepresents 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.
dccInquiryIdInquiry 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.
dccSkipOfferIf 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.
dynamicMerchantNameThe 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.
hideOrderDetailsSet this parameter to ‘true’ when you want to hide (remove) the ‘Your Order' box from our hosted payment page.
highRiskPurchaseIndicatorThis 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).
invoicenumberThis 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 item999Line 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
languageThis 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
mandateDateRepresents the date of the original mandate and is mandatory for recurring Direct Debit transactions.
The date needs to be submitted in 'YYYYMMDD' format.
mandateReferenceRepresents a mandate reference for Direct Debit payments. It is required to keep the Mandate Reference unambiguous.
mandateTypeRepresents 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
mandateUrlThe 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
marketplaceForeignRetailerIndicatorThis 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.
merchantTransactionIdOptional parameter to be submitted if needed for your future reference; can be used as a reference for cancelling / returning the primary order.
numberOfInstallmentsRepresents the number of instalments for a 'Sale' transaction.
installmentsInterestIndicates if an Installment payment includes interest.
Available values:
'true'
'false'
This parameter is available only to certain distribution channels in Latin America.
installmentDelayMonthsThis field should be used in case the Installment payment should be delayed for several months; alphanumeric with available values <2;99>
oidThis 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.
parentUriIf 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.
partialApprovalThe 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)
paymentMethodIf 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.
ponumberThis field serves to submit a Purchase Order Number; 50 characters max
referThis field describes who referred the customer to your store.
referencedMerchantTransactionIDThis field allows to reference to a merchantTransactionId of a transaction when performing a secondary transaction request, e.g. Return
referencedSchemeTransactionIdCredentials 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.
responseFailURLThe URL where you wish to direct customers after a declined or unsuccessful transaction (your Sorry URL)
responseSuccessURLThe URL where you wish to direct customers after a successful transaction (your Thank You URL)
shippingThis parameter can be used to submit the shipping fee, in the same format as chargetotal
If you submit shipping, the parameters subtotal and vattaxhave to be submitted as well.
The chargetotalmust be equal to subtotal +shipping + vattax
trxOriginRepresents 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
unscheduledCredentialOnFileTypeCredentials 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
vattaxRepresents Value Added Tax or other taxes, e.g.: GST in Australia.
Sub total amount + shipping + tax = charge total

Want a quick overview?