Optional HTML Form Fields

If you post a HTML form to initiate the payment, there are a number of optional fields that you can include in your request for different purpose.

Checkout Experience Related Fields

Field    Comment
checkoutoption  

This field allows you to set the checkout option to

  • 'simpleform' in case you want to work with an iFrame integration
  • ‘combinedpage’ in case you want to use a hosted payment page. Please note that this payment page version makes use of technical mechanisms that may not work with out-dated browser versions.
  • ‘classic’ for transactions with payment methods that are not supported with the other two options or cases where consumers use old operating systems with out-dated browser versions
idealIssuerID  

This parameter can be used to submit the iDEAL issuing bank in case you let your customers select the issuer within your shop environment. If you do not pass this value for an iDEAL transaction, a hosted selection form will be displayed to your customer.

iDEAL Issuer Value
ABN AMRO ABNANL2A
ING INGBNL2A
SNS Bank SNSBNL2A
van Lanschot FVLBNL22
Triodos Bank TRIONL2U
Knab KNABNL2H
Rabobank RABONL2U
RegioBank RBRBNL21
ASN Bank ASNBNL21
Bunq BUNQNL2A
language  

This parameter can be used to override the default payment page language configured for your merchant store.
The following values are currently possible:

Language Value
Chinese (simplified) zh_CN
Chinese (traditional) zh_TW
Czech cs_CZ
Dutch nl_NL
English (USA) en_US
English (UK) en_GB
Finnish fi_FI
French fr_FR
German de_DE
Greek el_GR
Italian it_IT
Polish pl_PL
Portuguese (Brazil) pt_BR
Serbian sr_RS
Slovak sk_SK
Spanish es_ES
mobileMode   Only in relation to checkoutoption 'classic': if your customer uses a mobile device for shopping at your online store you can submit this parameter with the value ‘true’. This will lead your customer to a payment page flow that has been specifically designed for mobile devices.
paymentMethod  

If you let the customer select the payment method (e. g. MasterCard, Visa, Direct Debit) in your shop environment or want to define the payment type yourself, transmit the parameter ‘paymentMethod’ along with your Sale or PreAuth transaction.
If you do not submit this parameter, the payment gateway will display a drop-down menu to the customer to choose from the payment methods available for your shop.

> See valid values here

responseFailURL   The URL where you wish to direct customers after a declined or unsuccessful transaction (your Sorry URL) – only needed if not setup in Virtual Terminal / Customization.
responseSuccessURL   The URL where you wish to direct customers after a successful transaction (your Thank You URL) – only needed if not setup in Virtual Terminal / Customization.

 

Transaction Identifiers

Field    Comment
merchantTransactionId  

Allows you to assign a unique ID for the transaction. This ID can be used to reference to this transactions in a PostAuth or Void request
(referencedMerchantTransactionId).

oid   This field allows you to assign a unique ID for your order. If you choose not to assign an order ID, the First Data system will automatically generate one for you.
Please note that for Direct Debit transactions, a maximum of 78 characters can be submitted to the bank.
referencedMerchantTransactionID   This field allows to reference to a merchantTransactionId of a
transaction when performing a Void. This can be used as an alternative to ipgTransactionId if you assigned a merchantTransactionId in the original transaction request.

 

Consumer Information

Field    Comment
customerid  

This field allows you to transmit any value, e. g. your ID for the customer.
Please note that for:

  • Direct Debit transactions, the Customer ID can be submitted to the bank, depending on the length of the Order ID. The maximum amount of characters that can be submitted to the bank is 78.
  • iDEAL transactions, the Customer ID can be submitted in your request filled in with any relevant data which can be populated in a field in the iDEAL TransactionRequest to be displayed on your consumers’ bank account statements.
ponumber   This field allows you to submit a Purchase Order Number with up to 50 characters.

 

Card Related Fields

Field    Comment
cardFunction  

This field allows you to indicate the card function in case of combo cards which provide credit and debit functionality on the same card. It can be set to ‘credit’ or ‘debit’.
The field can also be used to validate the card type in a way that transactions where the submitted card function does not match the card’s capabilities will be declined. If you e.g. submit “cardFunction=debit” and the card is a credit card, the transaction will be declined.

dccInquiryId   Inquiry ID for a Dynamic Pricing request. Used to send the Inquiry ID you have obtained via an API call. This value will be used to retrieve the currency conversion information (exchange rate, converted amount) for this transaction.
numberOfInstallments   This parameter allows you to set the number of instalments for a Sale transaction if your customer pays the amount in several parts.
installmentsInterest   This parameter allows you to choose, if instalment interest should be applied or not, the values “true” or “false” are currently possible.
installmentDelayMonths   This parameter allows you to delay the first instalment payment for several months, values 2-99 are currently possible.
 
Purchasing Cards - Level II Data

Field

 

Comment

pcCustomerReferenceID

 

Merchant-defined reference for the customer that will appear on the customer’s statement.

pcSupplierInvoiceNumber

 

Merchant-defined reference for the invoice – invoice number.

pcSupplierVATRegistrationNumber

 

The ID number assigned by the tax authorities to the merchant.

pcTotalDiscountAmount

 

Total discount applied to a transaction (i.e. total transaction percentage discounts, fixed transaction amount reductions or summarization of line item discounts).

pcTotalDiscountRate

 

Rate of discount for the whole transaction.

pcVATShippingRate

 

Total shipping amount applied to the transaction. Merchants can choose to deliver contents of a single transaction in multiple shipments and this field reflects the total cost of those deliveries

pcVATShippingAmount

 

Total shipping amount applied to the transaction. Merchants can choose to deliver contents of a single transaction in multiple shipments and this field reflects the total cost of those deliveries

pcLineItemsJson

 

Line item details in JSON format. See table below.

 
Purchasing Cards - Level III Data (line item details in JSON format)

Field

 

Comment

CommodityCode

 

Reference to a commodity code used to classify a purchased item.

ProductCode

 

Reference to a merchant product identifier – Universal Product Code (UPC) of a purchased item.

Description

 

Description of purchased item.

Quantity

 

Quantity of purchased items.

UnitOfMeasure

 

Unit of measure of purchased items.

UnitPrice

 

Mandatory data for Level III transactions.

VATAmountAndRate

 

Rate of the VAT amount e.g. 0.09 = 9%

DiscountAmountAndRate

 

Rate of the discounted amount e.g. 0.09 = 9%

LineItemTotal

 

Calculation of the unit cost multiplied by the quantity and less the discount per line item. [Unit Cost * Quantity] – Discount per Line Item = Line Item Total.

 
MCC 6012 Mandate in the UK

An MCC, or merchant category code, is a four-digit number assigned to a business by card companies. It is used to classify businesses by their goods or service offerings. In this particular instance, the merchant category code 6012 is for businesses who are classified as Financial Institutions.

For UK-based Financial Institutions with Merchant Category Code 6012, Visa and MasterCard have mandated additional information of the primary recipient of the loan to be included in the authorization message.

As per this mandate, you must use the following parameters for your transaction requests:

Field    Comment
mcc6012BirthDay  

Recipient date of birth in format: dd.mm.yyy

mcc6012AccountFirst6   First 6 digits of recipient PAN (where the primary recipient account is a card)
mcc6012AccountLast4   Last 4 digits of recipient PAN (where the primary recipient account is not a card)
mcc6012AccountNumber   Recipient account number (where the primary recipient account is not a card)
mcc6012Surname   Surname
mcc6012Zip   Post Code

 

Information Required For Specific Payment Methods

SEPA Direct Debit
Field    Comment
mandateDate  

This field allows you to reference to the date of the original mandate when performing recurring Direct Debit transactions. The date needs to be submitted in format YYYYMMDD. Please note that this is a mandatory field for recurring Direct Debit transactions.

mandateReference   This field allows you to transmit a Mandate Reference for Direct Debit payments. Please note the regulatory requisite to keep the Mandate Reference unambiguous.
mandateType   This field allows you to process Direct Debit transactions that are based on mandates for recurring collections. The mandate type can be set to ‘single’ for single (one-off) debit collections, to ‘firstCollection’ when submitting the initial transaction related to a mandate for recurring Direct Debit collections, to ‘recurringCollection’ for subsequent recurring transactions or to ‘finalCollection’ for the last direct debit in a series of recurring direct debits. Transactions where this parameter is not submitted by the merchant will be flagged as a single debit collection.
Please note that it is mandatory to submit a mandateReference in case of recurring collections.
mandateUrl   When your store is enabled for SEPA Direct Debit as part of the Local Payments offering, this field allows you to transmit a valid URL of SEPA Direct Debit mandate to enable the Risk and Compliance department to access the details.
Please note that it is mandatory to submit a mandateReference and a mandateDate together with a mandateUrl in case you manage SEPA Direct Debit mandates on your side in the combination with the Local Payments offering.
 
MasterPass
Field    Comment
reviewOrder  

MasterPass-specific parameter for scenarios where the final amount needs to be confirmed by the customer after returning from the Wallet. Set the value for this parameter to ‘true’ in order to indicate that the final transaction amount needs to be reviewed by the cardholder.

reviewURL   MasterPass-specific parameter for scenarios where the final amount needs to be confirmed by the customer after returning from the MasterPass environment. Use this parameter to indicate where the customer shall be redirected to in order to review and complete the transaction after having clicked on “Finish shopping” within the Wallet.
 
China Domestic Payments
Field    Comment
checkoutoption  

Set this parameter to ‘classic’ for China domestic payments

mode   Set this parameter to ‘payonly’ for China domestic payments
mobileMode   Set this parameter to ’false’ for China domestic payments
full_bypass   Set this parameter to ‘true’ for China domestic payments
item1  

Submit exactly one line item parameter with four (4) property values in the following format: id;description;quantity;item_total_price

Transaction request without a line item or with multiple line items will be declined. 
Example: 100018;The Hobbit;1;3.50

Position Property Description
1 id

Product code (编码Code)

> See valid values here

2 description Product name
3 quantity Quantity of product(s)
4 item_total_price Price of product(s)

 

customerid  

Unique reference to identify the consumer

 

Additional Transaction Information

Field    Comment
comments  

Place any comments here about the transaction.

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.
invoicenumber   This field allows you to transmit any value, e. g. an invoice number or class of goods. Please note that the maximum length for this parameter is 48 characters.
item1 up to item999  

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
'shipping' always has to be set to '0' for single line items. If you want to include a shipping fee for an order, please use the predefined id IPG_SHIPPING.
For other fees that you may want to add to the total order, you can use the predefined id IPG_HANDLING.
When you want to apply a discount, you should include an item with a negative amount and change accordingly the total amount of the order. Do not forget to regard the ‘quantity’ when calculating the values e.g.: subtotal and VAT since they are fixed by items.

Examples:
A;Product A;1;5;3;2;0
B;Product B;5;10;7;3;0
C;Product C;2;12;10;2;0
D;Product D;1;-1.0;-0.9;-0.1;0
IPG_SHIPPING;Shipping costs;1;6;5;1;0
IPG_HANDLING;Transaction fee;1;6.0;6.0;0;0

shipping   This parameter can be used to submit the shipping fee, in the same format as ‘chargetotal’. If you submit ‘shipping’, the parameters ‘subtotal’ and ‘vattax’ have to be submitted as well. Note that the ‘chargetotal’ has to be equal to ‘subtotal’ plus ‘shipping’ plus ‘vattax’.
trxOrigin   This parameter allows you to use the secure and hosted payment form capabilities within your own application for Mail/Telephone Order (MOTO) payments. Possible values are ‘MOTO‘ (for transactions where you have received the order over the phone or by mail and enter the payment details yourself) and ‘ECI‘ (for standard usage in an eCommerce environment where your customer enters the payment details).
vattax   This field allows you to submit an amount for Value Added Tax or other taxes, e.g. GST in Australia. Please ensure the sub total amount plus shipping plus tax equals the charge total.