Additional Form Fields
Introduction
This page contains a reference for additional fields available when using the Hosted Payment Page.
Billing & Shipping
You can include billing and shipping information in your request by using the following fields. Some of these fields are mandatory for specific alternative payment methods or relevant for fraud prevention purpose.
Billing Information
| Field | Description |
|---|---|
bcompany | Customer's company name. Alphanumeric characters, spaces and dashes limited to 96. |
bname | Customer's name. Alphanumeric characters, spaces and dashes limited to 96. |
baddr1 | Customer's billing address 1. Limit of 96 characters including spaces. |
baddr2 | Customer's billing address 2. Limit of 96 characters including spaces. |
bcity | Billing City. Limit of 96 characters including spaces. |
bstate | State, Province or Territory. Limit of 96 characters including spaces. |
bcountry | Country of Billing Address. Two letter country code. |
bzip | Zip or Postal Code. Limit of 24 characters including spaces. |
phone | Customer's Phone Number. Limit of 32 characters. |
fax | Customer's Fax Number. Limit of 32 characters. |
email | Customer's Email Address. Limit of 254 characters. |
Shipping Information
| Field | Description |
|---|---|
sname | Ship-to name. Alphanumeric characters, spaces and dashes limited to 96. |
saddr1 | Shipping Address Line 1. Limit of 96 characters including spaces. |
saddr2 | Shipping Address Line 2. Limit of 96 characters including spaces. |
scity | Shipping City. Limit of 96 characters including spaces. |
sstate | State, Province or Territory. Limit of 96 characters including spaces. |
scountry | Country of Billing Address. Two letter country code. |
szip | Zip or Postal Code. Limit of 24 characters including spaces. |
Custom Fields
You may want to use further fields to gather additional customer data geared towards your business specialty, or to gather additional customer demographic data which you can then store in your own database for future analysis. You can send as many custom fields to the payment Gateway as you wish, and they will get returned along with all other fields to the response URL.
Up to ten custom fields can be submitted in a way that they will be stored within the the Gateway so that they appear in the Virtual Terminal's Order Detail View as well as in the response to Inquiry Actions that you send through our Web Service API.
| Field Name | Description, possible values and format |
|---|---|
customParam_key | If you want to use this feature, please send the custom fields in the format customParam_key=valueThe maximum length of a custom parameter is 100 characters |
Example: <input type="hidden" name="customParam_color" value="green"/> |
To remain compliant the custom fields are not to be used to submit credit card detail or sensitive card holder information, please use the designated fields defined by the Gateway for this purpose.
Payment Methods
If your customers select the payment method within your webstore and you post a HTML form to initiate the payment, your request needs to contain a value for the parameter paymentMethod.
If you do not submit this parameter, a hosted form will be displayed to your customer to make the selection based on the payment methods that have been activated for your Store ID.
| Payment Method | Value |
|---|---|
| Alipay * | aliPay |
| American Express | A |
| Apple Pay on the web | applePay |
| Bancontact | BCMC |
| BLIK | blik_amp_ng |
| Diners | C |
| EPS * | eps |
| giropay | giropay |
| Google Pay | googlePay |
| iDEAL | ideal |
| JCB | J |
| Maestro | MA |
| Maestro UK | maestroUK |
| Mastercard | M |
| MyBank * | mybank |
| Paysafecard * | paySafeCard |
| PayPal | paypal |
| PostFinance Card | postfinance_card |
| PostFinance E-Finance | postfinance |
| Przelewy24 (P24) * | przelewy24 |
| RuPay | RU |
| SafetyPay * | safetypay |
| SEPA Direct Debit | debitDE |
| SEPA Direct Debit * | direct_debit-apm |
| Trustly * | trustly |
| TrustPay * | trustpay |
| UnionPay | CUP |
| Visa | V |
*Only supported in a collecting model through the Our Local Payments solution.
Server-to-server Notification
In addition to the response you received in hidden fields to your responseSuccessURL or responseFailURL, the Gateway can send server-to-server notifications with the above result parameters to a defined URL. This is useful to keep your systems in sync with the status of a transaction. To use this notification method, you can specify an URL in the Customisation section of the Virtual Terminal or submit the URL in the following additional transaction parameter transactionNotificationURL.
Please note, that:
• The transaction URL is sent as received therefore please don’t add additional escaping (e.g.: using %2f for a Slash(/).
• No SSL handshake or verification of SSL certificates will be done in this process.
• The notification URL needs to listen on port 443 (https) – other ports are not supported.
The response hash parameter for validation (using the same algorithm that you have set in the transaction request) notification_hash is calculated as follows:
chargetotal|currency|txndatetime|storename|approval_code
Shared secret (sharedsecret) will be used as a key in HMAC to calculate the hash with the above hash string.
Such notifications can also be set up for the recurring payments that get automatically triggered by the Gateway. Please contact your local support team to get a shared secret (rcpSharedSecret) agreed for these notifications. You can configure your Recurring Transaction Notification URL (rcpTransactionNotificationURL) in the Customisation section of the Virtual Terminal.
In case of the recurring transactions the response hash parameter notification_hash is calculated differently as follows:
chargetotal+rcpSharedSecret+currency+txndatetime+storename+approval_code
The shared secret (rcpSharedSecret) is part of the string (it is not used as a key in HMAC to calculate the hash with the hash string). Moreover, the response hash parameter for the recurring transaction notifications is calculated with the SHA256-value (as the default value).
Visa AFT
The Account Funding Transaction (AFT) is a transaction used to pull funds from a card account in order to fund a push OCT to a different account, which can be either the cardholder's or another person's account.
| Field Name | M/O | Description, possible values and format |
|---|---|---|
BusinessApplicationIdentifier | M | Represents the identity of the merchant participating in AFT program, available values: • ACCOUNT_TO_ACCOUNT • BANK_INITIATED_TRANSFER • BUSINESS_TO_BUSINESS • CARD_BILL_PAYMENT • FUNDS_DISBURSEMENT • FUND_TRANSFER • GAMBLING_PAYOUT • GENERAL_FUNDS_DISBURSEMENT • GOVERNMENT_DISBURSEMENT • LOYALTY_PAYMENTS • MERCHANT_DISBURSEMENT • MERCHANT_PAYMENT • NON_CARD_BILL_PAYMENT • ONLINE_GAMBLING_PAYOUT • PAYROLL_OR_PENSION_DISBURSEMENT • PERSON_TO_PERSON • TOPUP_FOR_ENHANCED_PREPAID_LOADS • TOP_OFF • WALLET_TRANSFER • ZERO_DOLLAR_AUTHORIZATION |
sdrName | M | Sender's Name |
sdrAccount | M | Sender's Account Number |
sdrReference | O | Sender Reference Number; contains a transaction reference number that is provided by the originator and can be used to uniquely identify the sender |
sdrAddr | M | Sender’s Address |
sdrCity | O | Sender’s City |
sdrState | O | Sender's State |
sdrPhone | O | Sender's Phone Number |
sdrCountry | M | Sender's Country |
rName | M | Recipient's Name |
rAccountNumber | M | Recipient's Account Number |
rReferenceNumber | M | Recipient's Reference Number |
The following represents an example of a Visa AFT transaction including mandatory and optional set of elements:
<!-- #include file="ipg-util.asp"-->
<html>
<head><title>IPG Connect Sample for ASP</title></head>
<body>
<p><h1>Order Form</h1></p>
<form method="post" action=" https://test.ipg-online.com/connect/gateway/processing ">
<input type="hidden" name="txntype" value="sale">
<input type="hidden" name="checkoutoption" value="combinedpage">
<input type="hidden" name="timezone" value="Europe/Berlin"/>
<input type="hidden" name="txndatetime" value="<% getDateTime() %>"/>
<input type="hidden" name="hash_algorithm" value="HMACSHA256"/>
<input type="hidden" name="hashExtended" value="<% call createExtendedHash( "13.00","978" ) %>"/>
<input type="hidden" name="storename" value="1109950006" />
<input type="hidden" name="mode" value="payonly"/>
<input type="hidden" name="paymentMethod" value="M"/>
<input type="text" name="chargetotal" value="130.00" />
<input type="hidden" name="currency" value="978"/>
<input type="hidden" name="authenticateTransaction" value="true"/>
<input type="hidden" name="threeDSRequestorChallengeIndicator" value=”1”/>
<input type="text" name="cardnumber" value="540215******2355">
<input type="text" name="expmonth" value="12">
<input type="text" name="expyear" value="24">
<input type="text" name="businessApplicationIdentifier" value="PAYROLL_OR_PENSION_DISBURSEMENT">
<input type="text" name="sdrName" value="Sender Name">
<input type="text" name="sdrAccount" value="1234567890">
<input type="text" name="sdrReference" value="sendRefNo123">
<input type="text" name="sdrAddr" value="Sender Address">
<input type="text" name="sdrCity" value="Sender City">
<input type="text" name="sdrState" value="Sender State">
<input type="text" name="sdrPhone" value="123456456789">
<input type="text" name="sdrCountry" value="Sender Country">
<input type="text" name="rName" value="Recipient Name">
<input type="text" name="rAccountNumber" value="Recipient Account Number">
<input type="text" name="rReferenceNumber" value="receiverReferenceNumber108">
<input type="submit" value="Submit">
</form>
</body>
</html>
Mastercard MoneySend
Mastercard MoneySend makes it possible to credit a Mastercard account (for a credit, debit or prepaid card) via the existing payments system infrastructure.
| Field Name | M/O | Description, possible values and format |
|---|---|---|
TransactionTypeIdentifier | M | Represents the identity of the merchant participating in AFT program, available values: • BUSINESS_DISBURSEMENT_MONEY_SEND • BUSINESS_DISBURSEMENT_MONEY_TRANSFER • BUSINESS_TO_BUSINESS_MONEY_SEND • BUSINESS_TO_BUSINESS_MONEY_TRANSFER • CARD_BILL_PAYMENT_MONEY_SEND • CARD_BILL_PAYMENT_MONEY_TRANSFER • GOVERNMENT_DISBURSEMENT_NONPROFIT • OWN_ACCOUNT_MONEY_SEND • OWN_ACCOUNT_MONEY_TRANSFER • OWN_DEBIT_PREPAID_TRANSFER • OWN_WALLET_TRANSFER • PERSON_TO_PERSON_CARD_ACCOUNT • PERSON_TO_PERSON_MONEY_SEND • PERSON_TO_PERSON_MONEY_TRANSFER • RAPID_MERCHANT_SETTLEMENT |
sdrName | M | Sender's Name |
sdrAccount | O | Sender's Account Number |
sdrReference | O | Sender Reference Number; contains a transaction reference number that is provided by the originator and can be used to uniquely identify the sender |
sdrAddr | O | Sender’s Address |
sdrCity | O | Sender’s City |
sdrState | O | Sender's State |
sdrPhone | O | Sender's Phone Number |
sdrCountry | O | Sender's Country |
rName | M | Recipient's Name |
rAccountNumber | M | Recipient's Account Number |
rReferenceNumber | O | Recipient's Reference Number |
rCountry | M | Recipient's Country |
The following represents an example of a Mastercard funding transaction including mandatory and optional set of elements:
<!-- #include file="ipg-util.asp"-->
<html>
<head><title>IPG Connect Sample for ASP</title></head>
<body>
<p><h1>Order Form</h1></p>
<form method="post" action=" https://test.ipg-online.com/connect/gateway/processing ">
<input type="hidden" name="txntype" value="sale">
<input type="hidden" name="checkoutoption" value="combinedpage">
<input type="hidden" name="timezone" value="Europe/Berlin"/>
<input type="hidden" name="txndatetime" value="<% getDateTime() %>"/>
<input type="hidden" name="hash_algorithm" value="HMACSHA256"/>
<input type="hidden" name="hashExtended" value="<% call createExtendedHash( "13.00","978" ) %>"/>
<input type="hidden" name="storename" value="1109950006" />
<input type="hidden" name="mode" value="payonly"/>
<input type="hidden" name="paymentMethod" value="M"/>
<input type="text" name="chargetotal" value="130.00" />
<input type="hidden" name="currency" value="978"/>
<input type="hidden" name="authenticateTransaction" value="true"/>
<input type="hidden" name="threeDSRequestorChallengeIndicator" value=”1”/>
<input type="text" name="cardnumber" value="540215******2355">
<input type="text" name="expmonth" value="12">
<input type="text" name="expyear" value="24">
<input type="text" name="transactionTypeIdentifier" value=" BUSINESS_DISBURSEMENT_MONEY_SEND">
<input type="text" name="sdrName" value="Sender Name">
<input type="text" name="sdrAccount" value="1234567890">
<input type="text" name="sdrReference" value="sendRefNo123">
<input type="text" name="sdrAddr" value="Sender Address">
<input type="text" name="sdrCity" value="Sender City">
<input type="text" name="sdrState" value="Sender State">
<input type="text" name="sdrPhone" value="123456456789">
<input type="text" name="sdrCountry" value="Sender Country">
<input type="text" name="rName" value="receiverReferenceNumber108">
<input type="text" name="rAccountNumber" value="Recipient Account Number">
<input type="text" name="rCountry" value="Recipient Country">
<input type="submit" value="Submit">
</form>
</body>
</html>
Purchasing Cards
Purchasing Cards offer businesses the ability to allow their employees to purchase items with a credit card while providing additional information on sales tax, customer code etc. When providing specific details on the payment being made with a Purchasing Card favourable addendum interchange rates are applied.
There are three levels of details required for Purchasing Cards:
• Level I - The first level is the standard transaction data; no enhanced data is required at this level.
• Level II - The second level requires that data such as tax amount and customer code be supplied in addition to the standard transaction date. (Visa only have a level II option)
• Level III - The third level allows a merchant to pass a detailed accounting of goods and services purchased to the buyer. All the data for Level I and Level II must also be passed to participate in Level III. (Visa and MasterCard).
You can submit Level II and Level III data in your transaction request using the following parameters:
| Field Name | Description |
|---|---|
pcCustomerReferenceID | Merchant-defined reference for the customer that will appear on the customer’s statement. |
pcSupplierInvoiceNumber | Merchant-defined reference for the invoice, e.g.: invoice number. |
pcSupplierVATRegistrationNumber | The Identification number assigned by the taxing authorities to the merchant. |
pcTotalDiscountAmount | The total discount amount applied to a transaction (i.e.: total transaction percentage discounts, fixed transaction amount reductions or summarization of line item discounts). |
pcTotalDiscountRate | The rate of the discount for the whole transaction. |
pcVatShippingRate | The total freight/shipping amount applied to the transaction. Merchants can choose to deliver the contents of a single transaction in multiple shipments and this field reflects the total cost of those deliveries. |
pcVatShippingAmount | The total freight/shipping amount applied to the transaction. Merchants can choose to deliver the 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 for more information. |
Purchasing Cards Line Item Details in JSON format:
| Field Name | Description |
|---|---|
CommodityCode | A reference to a commodity code used to classify purchased item. |
ProductCode | A reference to a merchant product identifier, the Universal Product Code (UPC) of purchased item. |
Description | Represents a description of purchased item. |
Quantity | Represents a quantity of purchased items. |
UnitOfMeasure | Represents a unit of measure of purchased items. |
UnitPrice | Represents mandatory data for Level III transactions. |
VATAmountAndRate | Represents a rate of the VAT amount, e.g.: 0.09 (means 9%). |
DiscountAmountAndRate | Represents a rate of the discount amount, e.g.: 0.09 (means 9%). |
LineItemTotal | This field is a calculation of the unit cost multiplied by the quantity and less the discount per line item. The calculation is reflected as: [Unit Cost * Quantity] - Discount per Line Item = Line Item Total. |
Response Reference
Upon completion, the transaction details will be sent back to the defined URL with hidden fields.
Standard set
| Field Name | Description | Value |
|---|---|---|
approval_code | Approval code for the transaction. The first character of this parameter is the most helpful indicator for verification of the transaction result. | Y indicates that the transaction has been successful, N indicates that the transaction has not been successful, ? indicates that the transaction has been successfully initialized, but a final result is not yet available since the transaction is now in a waiting status. The transaction status will be updated at a later stage. |
oid | Order ID, if not defined in the request, the Gateway generates it automatically | e.g. C-2101f68a-45e9-4f3c-a6da-1337d5574717 |
refnumber | Reference number | - |
status | Transaction status | APPROVED, DECLINED (by authorisation endpoint or due to fraud prevention settings),FAILED (wrong transaction message content/parameters, etc.) or WAITING (asynchronous Alternative Payment Methods) |
txndate_processed | Time of transaction processing | - |
ipgTransactionId | Transaction identifier assigned by the Gateway, e.g. to be used for a Void | - |
tdate | Identification for the specific transaction | - |
fail_reason | Reason the transaction failed | - |
response_hash | Hash-Value to protect the communication See note below | - |
extended_response_hash | Hash-Value to protect the communication, where all response parameters are included in the hash calculation see note below. | |
processor_response_code | The response code provided by the backend system. | Note that response codes can be different depending on the used payment type and backend system. While for credit card payments, the response code 00 is the most common response for an approval, the backend for giropay transactions for example returns the response code 4000 for successful transactions. |
fail_rc | Internal processing code for failed transactions | - |
terminal_id | Terminal ID used for transaction processing | - |
ccbin | 6 digit identifier of the card issuing bank | - |
cccountry | 3 letter alphanumeric ISO code of the cardholder’s country | e.g. USA, DEU, ITA, etc. Filled with N/A if the cardholder’s country cannot be determined or the payment type is not credit card |
ccbrand | Brand of the credit or debit card | MASTERCARD, VISA, AMEX, DINERSCLUB, JCB, CUP, CABAL, MAESTRO, RUPAY, BCMC, SOROCRED. Filled with N/A for any payment method which is not a credit card or debit card. |
Hash Validation
Make sure to use the parameter response_hash to recheck if the received transaction response has really been sent by Fiserv to protect you from fraudulent manipulations. The value is created with a HMAC Hash using the following parameter string:
approval_code|chargetotal|currency|txndatetime|storename
Shared secret (sharedsecret) will be used as a key in HMAC to calculate the hash with the above hash string. The hash algorithm is the same as the one that you have set in the transaction request.
Please note that you have to implement the response hash validation, when doing so remember to store the txndatetime that you have submitted with the transaction request in order to be able to validate the response hash. Furthermore, you must always use the https-connection (instead of http) to prevent eavesdropping of transaction details.
You can also use the parameter extended_response_hash to include all response parameters in the hash calculation. Please contact your local support team if you want to enable this feature. This will be managed with a specific setting performed on your account (service configuration extendedResponseHashSupported).
Creating the extended response hash:
- Step 1: Retrieve all non-empty Gateway specified response parameters and then remove the parameter
extended_response_hashfrom your list, so that it will not get included in the hash calculation. Consider also that shared secret will be used as a key in HMAC to calculate the hash and the hash algorithm must be the same as the one that you have set in the transaction request. - Step 2: Sort the response parameters in ascending order of the parameter names, where the upper-case characters come before the lower case (based on ASCII value). Join the parameters’ values to one string with pipe separator (use only parameters’ values and not the parameters’ names).
- Step 3: Pass the created string to the HMAC algorithm while using shared secret (‘sharedsecret’) as a key for calculating the hash value.
- Step 4: Encode the result of HMAC with Base64 to generate the extended response hash. Only HMAC algorithm (i.e.: HMACSHA256, HMACSHA384 or HMACSHA512) is supported for generating the extended response hash.
3-D Secure transactions
Response code indicates the classification of the transaction, values are valid for both HPP and APIs.
| Field Name | Description |
|---|---|
response_code_3dsecure ORresponseCode3dSecure | 1 - Successful authentication (VISA ECI 05, MasterCard ECI 02) 2 - Successful authentication without AVV (VISA ECI 05, MasterCard ECI 02) 3 - Authentication failed / rejected by the DS or ACS (transaction declined by the Gateway) 4 - Authentication attempt (VISA ECI 06, MasterCard ECI 01) 5 - Unable to authenticate / DS not responding (VISA ECI 07) 6 - Unable to authenticate / ACS or DS are unable to authenticate the cardholder (VISA ECI 07) 7 - Cardholder not enrolled for 3-D Secure (VISA ECI 07) - relevant for 3DS 1.0 8 - Invalid 3-D Secure values received 9 - Tokenisation (tokenised PAN, eWallet) |
Credential-on-file transactions
| Field Name | Description |
|---|---|
schemeTransactionId | Returned in the response by a scheme for stored credentials transactions to be used in subsequent transaction requests as a reference |
Currency Conversion transactions
| Field Name | Description |
|---|---|
dcc_foreign_amount | Converted amount in cardholder home currency. Decimal number with dot (.) as a decimal separator |
dcc_foreign_currency | ISO numeric code of the cardholder home currency. This transaction is performed in this currency |
dcc_margin_rate_percentage | Percent of margin applied to the original amount. Decimal number with dot (.) as a decimal separator |
dcc_rate_source | Name of the exchange rate source (e.g. Reuters Wholesale Inter Bank) |
dcc_rate | Exchange rate. Decimal number with dot (.) as a decimal separator |
dcc_rate_source_timestamp | Exchange rate origin time. Integer - Unix timestamp (seconds since 1.1.1970) |
dcc_accepted | Indicates if the card holder has accepted the conversion offer (response value ‘true’) or declined the offer (response value ‘false’) |
iDEAL transactions
| Field Name | Description |
|---|---|
accountOwnerName | Name of the owner of the bank account that has been used for the iDEAL transaction |
iban | IBAN of the bank account that has been used for the iDEAL transaction |
bic | BIC of the bank account that has been used for the iDEAL transaction |
SEPA Direct Debit as part of the Local Payments offering
| Field Name | Description |
|---|---|
mandateReference | Mandate reference as returned for the first direct debit transaction |
mandateDate | Date of the initial direct debit transaction as returned for the first transaction |
Validity & Errors
Additionally when using your own error page for negative validity checks (full_bypass=true):
| Field Name | Description |
|---|---|
fail_reason_details | Comma separated list of missing or invalid variables. Note that fail_reason_details will not be supported in case of payplus and fullpay mode. |
invalid_cardholder_data | true – if validation of card holder data was negative. false – if validation of card holder data was positive but transaction has been declined due to other reasons. |
Partial Approval
| Field Name | Description |
|---|---|
PartiallyApprovedAmount | Available balance as a partial amount approved. |
Status | Transaction status: ‘PARTIALLY APPROVED’. This unique status allows you to identify this transaction and subtract the partially approved amount from the total transaction amount, and request another form of payment, using split-tender functionality. |
Updated 3 months ago
