Parameters for opening payment form

The parameters required for Payment Page are passed in the object configObj or in the request URL (when opened in a separate tab). The list of required and optional parameters depends on the mode you choose for Payment Page opening.

For more information on customer data parameters, see Collecting customer data.

Warning: The protocol for opening the Payment Page payment form prohibits the use of the symbol ";" (semicolon) in the values of the passed parameters and in the request string.
Table 1. Payment Page invocation parameters
Parameter Mandatory Type Description Example
account_token No string The token of the bank card that will be used to perform a payment. In this case, on the generated payment page the bank card is preselected with the bank card details filled in.
Restriction: Available in the Purchase and Card Verify modes.

For details, see Payments by using tokens

  
addendum_data No string

This parameter contains all the booking itinerary data such as booking number, check-in and check-out dates, and hotel guest name and is applicable only to payments in travel industry.

The value of this parameter is obtained by converting addendum data in a single string by using the Base64 algorithm. For more information on how to calculate the addendum_data value, see Using addendum with itinerary data

  
avs_post_code No string Customer's postal code passed in case of the AVS check. WS13 6LG
avs_street_address No string Customer's street address passed in case of the AVS check. 4 Breadmarket Street
baseUrl No string The URL for opening the payment form (when it is necessary to provide an actual URL)  
best_before No string Date and time when the payment period expires. After the payment expiration date the customer is redirected to a page with the message that the time of possibility to proceed the payment is expired. Parameter is passed in the following format: YYYY-MM-DDThh:mm:ss±hh 2020-04-26T13:50:37+00:00
billing_address Custom string Street of the customer billing address 33 Store Street
billing_city Custom string City of the customer billing address London
billing_country Custom string Country of the customer billing address, in ISO 3166-1 alpha-2 format GB
billing_postal Custom string Postcode of the customer billing address BR1 1AA
billing_region Custom string Region or state of the customer billing address Greater London
billing_region_code No string

State, province, or region code in the ISO 3166-2 format. Example: DOR for Dorset.

If you specify this parameter, you need also to specify and populate the billing_country parameter.

 DOR
booking_info No string A string containing the Base64 encoded booking data (details)  
card_holder No string Name of the cardholder as specified on the card. When the parameter is passed, the value is displayed and editable on the payment form CARD HOLDER
card_operation_type No string Type of payment performed via payment card. The following options are available:
  • sale: payment with direct withdrawal of funds
  • auth: payment with held funds

For more information, see Purchase processing and Authorisation hold

 sale
checkout_script No integer

A parameter that determines the possibility to make a payment or to verify card by the card token using an encryption script without entering CVV/CVC/CID (allowed values: 0 and 1). For more information, see Card data encryption script

When working with Payment Page without using the merchant.js library, a boolean value can be specified in this parameter.

 1
close_on_missclick No integer A parameter that specifies the action of the widget (opened in the modal window) when a customer clicks outside the widget area. The following options are available:
  • 1: The widget is closed
  • 0: The widget remains open. This option is set as default

For more information, see Opening Payment Page in a modal window

When working with Payment Page without using the merchant.js library, a boolean value can be specified in this parameter.

 1
css_modal_wrap No string An additional CSS class for a modal window. For more information, see Opening Payment Page in a modal window modal-popup
customer_address Custom string Address of the customer Main Street, 12
customer_account_info No string

This parameter contains the customer account and contact information on record with the web service.

The value of this parameter is obtained by converting the customer data into a single string by using the Base64 algorithm. For more information, see 3‑D Secure authentication.

  
customer_account_number No string Customer account or e-wallet number, can be also the email address or phone number (specified using a country code and without the + sign) linked to the account example@mail.com
customer_birthplace Custom string Customer place of birth London
customer_city Custom string City of the customer address London
customer_country Custom string Country of the customer address in ISO 3166-1 alpha-2 format GB
customer_day_of_birth Custom string Customer date of birth, DD-MM-YYYY 12-12-1990
customer_email Custom string Customer e-mail smith@gmail.com
customer_first_name Custom string Customer first name Jane
customer_id Mandatory for Card Tokenize, Purchase string Unique ID of the customer in your project. The data passed in the parameter is collected and displayed in Dashboard customer_341
customer_last_name Custom string Customer last name Smith
customer_middle_name Custom string Customer middle name Mary
customer_mpi_result No string

This parameter contains the information about the previous authentication procedure of the customer.

The value of this parameter is obtained by converting the authentication data into a single string by using the Base64 algorithm. For more information, see 3‑D Secure authentication.

  
customer_phone Custom string

Customer's phone number.
Generally, must be specified in full, with the country code, although in certain cases (such as card payments) the country code is not required.
Technically, the number must include from 4 to 24 digits, and if no additional restrictions are applied within the project and the payment method in use, it can also include punctuation marks and special characters.

443031237300
+1 212-963-3209
customer_security_code No string Customer account or e-wallet security code for payment confirmation 852923
customer_shipping No string

This parameter contains the shipping information.

The value of this parameter is obtained by converting the shipping data into a single string by using the Base64 algorithm. For more information, see 3‑D Secure authentication.

  
customer_ssn Custom integer The last 4 digits of the social security number in the USA 1234
customer_state Custom string State or region of the customer address Greater London
customer_street No string Street of the customer address Main
customer_zip Custom string Postcode of the customer address RdWC2N 5DU
debt_account No string The recipient's account number for debiting funds from the customer's card in order to repay the debt. Latin letters and numbers are allowed, the maximum length is 10 characters an9876170i
descriptor No string Information which identifies the merchant that performs the operation (more). The maximum length is 13. It is possible to use letters of the Latin alphabet, digits, and the following symbols: # $ * ( ) - _ = + " ; : ? \ / , . ` ' ^ "Merchant_1"
force_acs_new_window No integer The forced display mode with the ACS page opening in a new window despite the settings in Payment Page
  • 1: opening in a separate tab
  • 0 or not passed: opening as specified previously

When working with Payment Page without using the merchant.js library, a boolean value can be specified in this parameter.

 1
force_payment_method No string The ID of the payment method that is opened to customers without an option to select another one. The list of codes is provided in Payment method codes card
force_payment_group No string

Identifier of the payment method group, the elements of which limit the choice of method in the payment form. When specifying this identifier, Payment Page displays buttons for selecting only the methods that are included in the specified group and are available within the project. At the same time, when this identifier is specified in a single request along with the code of a specific method in the force_payment_method parameter, the payment form is opened for making a purchase by using the specified method, without taking into account the selected group.

Currently only the Open Banking group of methods is selectable by using the openbanking identifier.

 openbanking
force_payment_method_subtype No string The bank card type that is opened to customers by default if force_payment_method=card without an option to select another type. Also applies to the saved cards display. For available options see Payment card codes visa
hide No string The ID of the payment method that is hidden from customers on Payment Page. If it is necessary to hide several methods, identifiers are comma-separated. The list of codes is provided in Payment method codes card, cup-card
identify_doc_number No string Number of a customer identity document 6543234567
interface_type No string String containing information on the source of a payment request. The data is collected in a JSON object. Available value for the id parameter: 7 – Payment Page in iframe mode interface_type: {"id":7}
language_code Recommended string The language in which the payment page will be opened to the customer in ISO 639-1 alpha-2 format. By default, it is determined by the customer IP address en
merchant_callback_url No string The URL to deliver callbacks with information about specific target actions to. Useful when you need to change the callback URL for a specific request (details).  
merchant_data No string The parameter for specifying extended information about the purchase in progress (for example, details of the services provided). Data is passed as a JSON object. For more information, see Specifying other extended purchase data.  
merchant_fail_enabled No integer The parameter responsible for the possibility of returning customers to the project after a failed payment. For more information, see Options for redirecting customers to the web service 1
merchant_fail_redirect_mode No string Mode for opening the project page to which a customer is returned after a failed payment. For more information, see Options for redirecting customers to the web service iframe
merchant_fail_url No string The project page URL to which a customer is returned after a failed payment by clicking on the return button. For more information, see Options for redirecting customers to the web service http://example.com
merchant_return_enabled No integer The parameter responsible for the possibility of returning customers to the project at any payment step by clicking on the return button. For more information, see Options for redirecting customers to the web service 1
merchant_return_redirect_mode No string Mode for opening the project page to which a customer is returned at any payment step by clicking on the return button. For more information, see Options for redirecting customers to the web service iframe
merchant_return_url No string The project page URL to which a customer is returned at any payment step by clicking on the return button. For more information, see Options for redirecting customers to the web service http://example.com
merchant_success_enabled No integer The parameter responsible for the possibility of returning customers to the project after a succeeded payment. For more information, see Options for redirecting customers to the web service 1
merchant_success_redirect_mode No string Mode for opening the project page to which a customer is returned after a succeeded payment. For more information, see Options for redirecting customers to the web service iframe
merchant_success_url No string The project page URL to which a customer is returned after a successful payment by clicking on the return button. For more information, see Options for redirecting customers to the web service http://example.com
mode Mandatory for all modes, except Purchase string

Payment Page mode. The following values are available:

  • purchase: the Purchase mode. This mode is used by default
  • card_tokenize: the Card Tokenize mode
  • card_verify: the Card Verify mode
 card_tokenize
moto_type No integer Parameter that indicates Mail Order/Telephone Order (MO/TO) payment. The following values are available:
  • 1: MO payment
  • 2: TO payment
 2
payment_amount Mandatory for Purchase, Card Verify integer Payment amount specified in minor units of the payment currency. Restrictions:
  • for Purchase and Card Tokenize modes:
    • "minimum": 1
    • "maximum": 10000000000000
  • for Card Verify mode:
    • "minimum": 0
    • "maximum": 0
 10000
payment_currency Mandatory for Purchase, Card Verify string Payment currency in ISO 4217 alpha-3 format USD
payment_description Recommended string Payment description Order 3178
payment_extra_param No string The parameter that contains extra payment processing settings. For more information regarding this option, you may apply to your Key Account Manager  
payment_id Mandatory for Purchase, Card Verify string Identifier of the payment, must be unique within the project. It is case-insensitive and can contain up to 255 random characters. order_314
payment_merchant_risk No string

This parameter contains the purchase details and the authentication flow which is preferable for the merchant.

The value of this parameter is obtained by converting the customer data into a single string by using the Base64 algorithm. For more information, see 3‑D Secure authentication.

  
payment_methods_options No string A string containing the specific display options for the payment page opening or the payment method selection. The data is collected in a JSON object. For more information, see Methods in the sections on performing payments through Banks of South-East Asia  
project_id Yes integer Unique ID of your project in the Payment Page system 133
receipt_data No string A string containing the coded data to send electronic sales receipt to a customer. The data is collected into a JSON object and encoded into Base64. For more information, see Sending receipts and notifications to customer  
recurring No string A string containing details about a COF purchase as a JSON object—if the payment form is opened via the JavaScript library of ecommpay—or as a string generated as a result of URL encoding—if the payment form is opened via another method. For more information, see the COF purchase registration article.  
recurring_register No integer

Parameter that indicates whether this payment should be registered as recurring (allowed values: 0 or 1).

When working with Payment Page without using the merchant.js library, a boolean value can be specified in this parameter.

 1
redirect No integer A parameter that enables opening of the generated payment page in a separate tab. The following options are available:
  • 1: opening in a separate tab
  • 0 or not passed: opening as specified previously

For more information, see Opening Payment Page as a separate HTML page

When working with Payment Page without using the merchant.js library, a boolean value can be specified in this parameter.

 1
redirect_fail_mode No string The mode for customer redirection when the payment failed. The following options are available:
  • iframe. This mode is used by default
  • parent_page
  • blank_page: opening in a new tab. Pop-up blocking should be disabled in the customer browser.
parent_page
redirect_fail_url No string The URL of the page in your project to which the customer is redirected when the payment failed. Redirection occurs automatically without additional actions from customers. If the blank_page mode is used, the page with the result is displayed on a separate tab, in other modes – is not displayed http://merchant.site.com
redirect_on_mobile No integer A parameter that enables opening of the generated payment page in a separate tab on mobile devices only. The following options are available:
  • 1: opening in a separate tab
  • 0 or not passed: opening as specified previously

For more information, see Opening Payment Page as a separate HTML page

When working with Payment Page without using the merchant.js library, a boolean value can be specified in this parameter.

 1
redirect_success_mode No string The mode for customer redirection after a successful payment. The following options are available:
  • iframe. This mode is used by default
  • parent_page
  • blank_page: opening in a new tab. Pop-up blocking should be disabled in the customer browser.
parent_page
redirect_success_url No string The URL of the page in your project to which the customer is redirected after a successful payment. Redirection occurs automatically without additional actions from customers. If the blank_page mode is used, the page with the result is displayed on a separate tab, in other modes – is not displayed http://merchant.site.com
redirect_return_url No string The URL of the page in your project to which the customer is redirected from payment page on external provider site at any step before the payment is completed by clicking the return button. For more information about this functionality, refer to the ecommpay Key Account Manager http://merchant.site.com
redirect_tokenize_mode No string The mode for customer redirection once a token is generated in the Card Tokenize mode

The following options are available:

  • iframe. This mode is used by default
  • parent_page
 parent_page
redirect_tokenize_url No string The URL of the page in your project to which the customer is redirected after a successful token generation in the Card Tokenize mode  
region_code No string The customer country in ISO 3166-1 alpha-2 format. By default the region is determined by the IP address of the customer us
signature Yes string The signature to be passed in the request to open the payment page. For more information, see Signature generation and verification  
target_element No string The element in which the iframe of the payment page is embedded in the web page of your project. For more information, see Opening Payment Page in an iframe element of an HTML page pay_button_id
terminal_id No Integer Unique ID of the Payment Page template which you want to run despite the regional and A/B test settings 54