Parameters for opening payment form

This article describes parameters used to open Payment Page, including basic information about them and links to related articles, which contain descriptions of the parameters' functionality and set out possible scenarios for their use.

Parameters marked in this list as required must be included in all Payment Page calls intended to process payments. In the Card Tokenize mode, the following parameters are not required: payment_amount, payment_currency, payment_id.

Parameters marked in this list as optional can be used as additional parameters for specific projects and payment methods. Moreover, the inclusion of some parameters is recommended for specific use casesin order to avoid the customer being subjected to the 3‑D Secure authentication procedure (i.e., undergo authentication via the frictionless flow instead of the challenge flow; details) and having to provide additional payment information, as well as for other improvements to custom scenarios and the general functionality of the payment form.

If you have any additional questions about whether specific parameters are required or recommended for different individual use cases, consult the existing documentation and the ecommpay technical support specialists.

Parameter Description

account_token
string, optional

Payment instrument token.

Consists of an identifier obtained for a specific payment instrument from the payment platform when data for that instrument is saved. Can be used to perform payments using that saved data (i.e., when making a purchase).

Example: 42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021

addendum_data
string, optional

Booking itineraryBooking itinerary information.

Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme. Can be used to pay for services of companies in the travel industry, making the payments more secure and allowing for more competitive payment processing rates (see Using addendum with itinerary data). Subject to regulations of the Mastercard and Visa global card schemes.

Figure 1. Example JSON object
{
  "lodging": {
    "customer_service_toll_free_number": "18005553535", // Customer service phone 
    "guest_name": "John Smith",        // Guest name
    "check_in_date": "10-12-2019",     // Checkin date
    "check_out_date": "22-12-2019",    // Checkout date
    "folio_number": "56265655ABC",     // Booking ID
    "fire_safety_act_indicator": true, // Fire safety compliance indicator
    "room": {            // Object with the room details
        "rate": 12,                 // Daily room rate
        "number_of_nights": "12"    // Booked nights number
    },
    "charges": {            // Object with the charges details
        "transportation": 1200,       // Transportation charges
        "internet_access": 4500       //  Internet access charges
    }
  }
}
Figure 2. Example resulting string
ewogImxvZGdpbmciOiB7CiAgImN1c3RvbWVyX3NlcnZpY2VfdG9sbF9mcmVlX251bWJlciI6ICIx
ODAwNTU1MzUzNSIsCiAgImd1ZXN0X25hbWUiOiAiSm9obiBTbWl0aCIsICAgCiAgImNoZWNrX2lu
X2RhdGUiOiAiMTAtMTItMjAxOSIsICAgICAKICAiY2hlY2tfb3V0X2RhdGUiOiAiMjItMTItMjAx
OSIsCiAgImZvbGlvX251bWJlciI6ICI1NjI2NTY1NUFCQyIsCiAgImZpcmVfc2FmZXR5X2FjdF9p
bmRpY2F0b3IiOiB0cnVlLAogICJyb29tIjogeyAgICAgICAKICAicmF0ZSI6IDEyLCAgCiAgIm51
bWJlcl9vZl9uaWdodHMiOiAiMTIiIAogIH0sCiAgImNoYXJnZXMiOiB7ICAgICAgCiAgInRyYW5z
cG9ydGF0aW9uIjogMTIwMCwgICAKICAiaW50ZXJuZXRfYWNjZXNzIjogNDUwMCAgCiAgfQogfQp9

avs_post_code
string, optional

The postal code of the customer to be used in the Address Verification ServiceAVS check.

Example: WS13 6LG

avs_street_address
string, optional

The address of the customer to be used in the Address Verification ServiceAVS check.

Consists of a house number and a street name.

Example: 4 Breadmarket Street

baseUrl
string, optional

The base URL used to open the payment form.

Must be specified when a root address different from the default one (https://paymentpage.ecommpay.com) has been approved by the ecommpay account manager, in cases where the address needs to be provided explicitly.

Example: https://cosmopage.site.com

best_before
string, optional

The date and time in the specified timezone until which the customer is able to use the payment form to confirm their targeted actionafter which the customer can no longer use the payment form (see this article).

Should be specified in the following format: YYYY-MM-DDThh:mm:ss±hh.

Example: 2024-04-26T13:50:37+00

billing_address
string, optional

The house number (including any additional parts of the address such as building indicators and apartment numbers) and the name of the street in street name of the customer's billing address.

When the parameter is passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer (i.e., authentication via the frictionless flow instead of the challenge flow; details).

Example: 33 Store Street

billing_city
string, optional

The name of the city in the customer's billing address.

When the parameter is passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer (i.e., authentication via the frictionless flow instead of the challenge flow; details).

Example: London

billing_country
string, optional

The country code in the customer's billing address in the ISO 3166-1 alpha-2 format.

Specified in the ISO 3166-1 alpha-2 format. When the parameter is passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer (i.e., authentication via the frictionless flow instead of the challenge flow; details).

Example: GB

billing_postal
string, optional

The postal code in the customer's billing address.

When the parameter is passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer (i.e., authentication via the frictionless flow instead of the challenge flow; details).

Example: BR1 1AA

billing_region
string, optional

The name of the region (i.e., state, province, or other administrative division type) in the customer's billing address.

When the parameter is passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer (i.e., authentication via the frictionless flow instead of the challenge flow; details).

Example: Greater London

billing_region_code
string, optional

The recipient's country subdivision code (state, province, region, or territory). The value of this parameter is the second element of a code for a subdivision (in ISO 3166-2), without the two-letter country code and the hyphen-minus used as a separator. This parameter should be specified in requests where the billing_country parameter is also specified. When the parameter is passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer (i.e., authentication via the frictionless flow instead of the challenge flow; details).

The internal region code in the customer's billing address.

Consists of the second part of the ISO 3166-2 international territory code (without the two-letter country code or the separating hyphen) and should be specified in requests where the billing_country parameter is also specified.

Example: DOR

booking_info
string, optional

Booking information tracked by the web service (see this article).

Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme. Can be used to record and track relevant data about payments rendered for services by various organisations (see this article).

Figure 3. Example JSON object
"booking_info": {
    "firstname": "William",
    "surname": "Herschel",
    "email": "rsfellow@mail.com",
    "start_date": "12-08-2026",
    "end_date": "13-08-2026",
    "description": "Sideris music festival full pass",
    "total": 200000,
    "pax": 4,
    "reference": "musicfestlink",
    "id": "83"
}
Figure 4. Example resulting string
ewogICAgImZpcnN0bmFtZSI6ICJXaWxsaWFtIiwKICAgICJzdXJuYW1lIjogIkhlcnNjaGVsIiwKICAgICJlbWFpbCI6ICJyc2ZlbGxvd0BtYWlsLmNvbSIsCiAgICAic3RhcnRfZGF0ZSI6ICIxMi0wOC0yMDI2IiwKICAgICJlbmRfZGF0ZSI6ICIxMy0wOC0yMDI2IiwKICAgICJkZXNjcmlwdGlvbiI6ICJTaWRlcmlzIG11c2ljIGZlc3RpdmFsIGZ1bGwgcGFzcyIsCiAgICAidG90YWwiOiAyMDAwMDAsCiAgICAicGF4IjogNCwKICAgICJyZWZlcmVuY2UiOiAibXVzaWNmZXN0bGluayIsCiAgICAiaWQiOiAiODMiCn0=

card_holder
string, optional

The first and last name of the payment card holder.

Data specified in this parameter can be used to fill in the corresponding fields on the payment form in advance—this data can then still be edited by the customer—and should be spelled as specified on the card and adhere to the rules for specifying names (see this article).

Example: John Doe

card_operation_type
string, optional

Indicator that specifies whether a purchase made using a payment card is processed in one or two steps.

Indicator that specifies the type of purchase made using a payment card with the 4th generation of Payment Page or earlier:

Should be specified in cases where the intended payment type is different from the one specified by default (with regard to the number of steps). Can have one of the following values:

  • sale—for one-step purchases (with the funds transferred to the merchant immediately; details),
  • auth—for two-step purchases (with the funds transferred to the merchant after first being in an authorisation hold; details).

Should be specified in cases where the intended payment type is different from the one specified by default.

Can be used for the 4th generation of Payment Page or earlier.

Example: auth

close_on_missclick
integer (boolean*), optional

Indicator that specifies the action to be taken if the customer clicks outside of the borders of a payment form opened in a modal window.:

Should be specified for calls that make use of a modal window. Can have one of the following values:

  • 0—do not close the payment form (used by default),
  • 1—close the form.

If the merchant.js library is used (details), this parameter can be specified as a boolean value and set to either false or true.

Example: 1

css_modal_wrap
string, optional

Indicator for an additional CSS class to wrap the payment form inside of a modal window.

Should be specified for calls that make use of a modal window.

Example: CosmoshopModal

customer_address
string, optional

The name of the street and the house number (including any additional parts of the address such as building indicators and apartment numbers) in the customer's address, separated by a comma.

The length of the string cannot be more than 255 characters. Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios (see this article).

Example: Main Street, 12

customer_account_info
string, optional

Information about the customer's account and contact details obtained by the web service (see this article).

Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.

Figure 5. Example JSON object
{ 
  "customer":{ 
    "address_match":"Y",
    "home_phone":"442055526608",
    "work_phone":"442055537709",
    "account":{ 
      "additional":"gamer12345",
      "age_indicator":"01",
      "date":"01-10-2022",
      "change_indicator":"01",
      "change_date":"01-10-2022",
      "pass_change_indicator":"01",
      "pass_change_date":"01-10-2022",
      "purchase_number":12,
      "provision_attempts":16,
      "activity_day":22,
      "activity_year":222,
      "payment_age_indicator":"01",
      "payment_age":"01-10-2022",
      "suspicious_activity":"01",
      "auth_method":"01",
      "auth_time":"01-10-202213:12",
      "auth_data":"login_0102"
    }
  }
}
Figure 6. Example resulting string
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAiYWRkcmVzc19tYXRjaCI6IlkiLAogICAgImhvbWVfcGhvbmUiOiI0NDIwNTU1MjY2MDgiLAogICAgIndvcmtfcGhvbmUiOiI0NDIwNTU1Mzc3MDkiLAogICAgImFjY291bnQiOnsgCiAgICAgICJhZGRpdGlvbmFsIjoiZ2FtZXIxMjM0NSIsCiAgICAgICJhZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAiZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAiY2hhbmdlX2luZGljYXRvciI6IjAxIiwKICAgICAgImNoYW5nZV9kYXRlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJwYXNzX2NoYW5nZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJwYXNzX2NoYW5nZV9kYXRlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJwdXJjaGFzZV9udW1iZXIiOjEyLAogICAgICAicHJvdmlzaW9uX2F0dGVtcHRzIjoxNiwKICAgICAgImFjdGl2aXR5X2RheSI6MjIsCiAgICAgICJhY3Rpdml0eV95ZWFyIjoyMjIyLAogICAgICAicGF5bWVudF9hZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAicGF5bWVudF9hZ2UiOiIwMS0xMC0yMDIyIiwKICAgICAgInN1c3BpY2lvdXNfYWN0aXZpdHkiOiIwMSIsCiAgICAgICJhdXRoX21ldGhvZCI6IjAxIiwKICAgICAgImF1dGhfdGltZSI6IjAxLTEwLTIwMjIxMzoxMiIsCiAgICAgICJhdXRoX2RhdGEiOiJsb2dpbl8wMTAyIgogICAgfQogIH0KfQ=====

customer_account_number
string, optional

The identifier assigned to the customer's account by the payment system.

May be required when using specific payment methods (e.g., Neteller and OVO Wallet). Depending on the particular method, may consist of an e-wallet identifier, an email address, a phone number, or a different kind of identifier.

Example: example@mail.com

customer_birthplace
string, optional

The name of the customer's birthplace (e.g., town, city, or other settlement type).

The length of the string cannot be more than 255 characters. Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios (see this article).

Example: London

customer_city
string, optional

The name of the place of residence (e.g., town, city, or other settlement type) in the customer's address.

The length of the string cannot be more than 255 characters. Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios (see this article).

Example: London

customer_country
string, optional

The country code in the customer's address (in ISO 3166-1 alpha-2 format).

Specified in ISO 3166-1 alpha-2 format. Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios (see this article).

Example: GB

customer_day_of_birth
string, optional

The date of birth of the customer in DD-MM-YYYY format.

Consists of a string specified in DD-MM-YYYY format. Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios (see this article).

Example: 12-12-1990

customer_email
string, optional

The email address of the customer.

The length of the string cannot be more than 255 characters. The string consists of a local-part and a domain name, separated by the "@" symbol. Required for purchases made using a payment card if the customer_phone parameter is not specified and the customer is not provided an opportunity to specify their phone number themselves (see this article).

Example: helen@example.com

customer_first_name
string, optional

The first name of the customer.

The length of the string cannot be more than 255 characters. Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios (see this article).

Example: Jane

customer_id
string, required

The identifier assigned to the customer within the scope of the project (specified in project_id).

Each web service account should be linked to only one identifier and vice versa. This requirement is intended to address various risks and fraudulent operations.

Example: customer_112

customer_last_name
string, optional

The last name of the customer.

The length of the string cannot be more than 255 characters. Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios (see this article).

Example: Smith

customer_middle_name
string, optional

The middle, second, or patronymic name of the customer.

The length of the string cannot be more than 255 characters. Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios (see this article).

Example: Mary

customer_mpi_result
string, optional

Information about the customer's most recent authentication via the 3‑D Secure protocol (see this article).

Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme. When passed for card purchases, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer (i.e., authentication via the frictionless flow instead of the challenge flow; details).

Figure 7. Example JSON object
{ 
  "customer":{ 
    "mpi_result":{ 
      "acs_operation_id":"00000000-0005-5a5a-8000-016d3ea31d54",
      "authentication_flow":"01",
      "authentication_timestamp":"202210111050"
    }
  }
}
Figure 8. Example resulting string
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAibXBpX3Jlc3VsdCI6eyAKICAgICAgImFjc19vcGVyYXRpb25faWQiOiIwMDAwMDAwMC0wMDA1LTVhNWEtODAwMC0wMTZkM2VhMzFkNTQiLAogICAgICAiYXV0aGVudGljYXRpb25fZmxvdyI6IjAxIiwKICAgICAgImF1dGhlbnRpY2F0aW9uX3RpbWVzdGFtcCI6IjIwMjIxMDEwMTA1MCIKICAgIH0KICB9Cn0===

customer_phone
string, optional

The phone number of the customer.

Generally, should include the country code and contain between 4 and 24 digits.

Generally, should include the country code; however, some cases do not require a country code to be specified.

Should contain between four and 24 digits. If a particular project and payment method allow for the inclusion of punctuation marks and special characters in the phone number, the parameter can contain such characters in those cases; this is usually specially arranged beforehand. Required for purchases made using a payment card if the customer_email parameter is not specified and the customer is not provided an opportunity to specify their email address themselves (see this article).

Example: 443031237300

customer_security_code
string, optional

The customer's purchase confirmation code.

Some payment methods may require this parameter (depending on the methods themselves).

Example: 852923

customer_shipping
string, optional

Information about the delivery of a product or a service rendered to the customer (see this article).

Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme. When passed for card purchases, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer (i.e., authentication via the frictionless flow instead of the challenge flow; details).

Figure 9. Example JSON object
{ 
  "customer":{ 
    "shipping":{ 
      "type":"01",
      "delivery_time":"01",
      "delivery_email":"test@gmail.com",
      "address_usage_indicator":"01",
      "address_usage":"01-10-2022",
      "city":"London",
      "country":"GB",
      "address":"Blackheath Ave",
      "postal":"SE10 8XJ",
      "region_code":"LND",
      "name_indicator":"01"
    }
  }
}
Figure 10. Example resulting string
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAic2hpcHBpbmciOnsgCiAgICAgICJ0eXBlIjoiMDEiLAogICAgICAiZGVsaXZlcnlfdGltZSI6IjAxIiwKICAgICAgImRlbGl2ZXJ5X2VtYWlsIjoidGVzdEBnbWFpbC5jb20iLAogICAgICAiYWRkcmVzc191c2FnZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJhZGRyZXNzX3VzYWdlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJjaXR5IjoiTG9uZG9uIiwKICAgICAgImNvdW50cnkiOiJHQiIsCiAgICAgICJhZGRyZXNzIjoiQmxhY2toZWF0aCBBdmUiLAogICAgICAicG9zdGFsIjoiU0UxMCA4WEoiLAogICAgICAicmVnaW9uX2NvZGUiOiJMTkQiLAogICAgICAibmFtZV9pbmRpY2F0b3IiOiIwMSIKICAgIH0KICB9Cn0==

customer_ssn
integer, optional

The last four digits of the social security number of a US citizen.

Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios (see this article).

Example: 1984

customer_state
string, optional

The name of the region (state, province, or other administrative subdivision type) of in the customer's address.

The length of the string cannot be more than 255 characters. Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios (see this article).

Example: Greater London

customer_street
string, optional

The name of the street in the customer's address.

The length of the string cannot be more than 255 characters. Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios (see this article).

Example: Main

customer_zip
string, optional

The postal or zip code in the customer's address.

Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios (see this article).

Example: 75001

debt_account
string, optional

The number of the account designated to receive funds as part of debt settlement purchases (see this article).

This parameter is required for debt settlement purchases (see this article). The length of the string cannot be more than ten characters. Only Latin-script letters and digits are allowed.

Example: an9876170i

force_acs_new_window
integer (boolean*), optional

Indicator specifying whether a third-party web service that the customer is redirected to is opened in a new tab or not (see this article).:

May be required for specific payment methods and can have one of the following values:

  • 0—redirected using the mode specified as the default mode for the payment method,
  • 1—redirected in a new tab, ignoring the mode specified as the default mode for the payment method.

If the merchant.js library is used (details), this parameter can be specified as a boolean value and set to either false or true.

Example: 1

force_payment_method
string, optional

The code of the payment method that should be preselected for the payment (see this article); should correspond to the code for the relevant method from the payment method code list.

Can have values specified in the payment method code list.

Example: paypal-wallet

force_payment_group
string, optional

The code of the payment method group that should be preselected for the payment (see this article).

If this parameter is passed, only those payment methods that are part of the corresponding method group and are supported within the project will be available to the customer. However, if this parameter is passed together with the force_payment_method parameter, only the payment method linked to the code specified in that parameter will be preselected in the payment form, while the payment method group code will be ignored.

Currently, this parameter can be used to preselect the Open Banking method group when you work with the 4th generation Payment Page—to do so, specify openbanking as the value.

When passed together with the force_payment_method parameter, that parameter will have priority.

Example: openbanking

force_payment_method_subtype
string, optional

The code of the payment card brand that should be preselected for the payment (see this aticle); should correspond to the code for the relevant card brand from the payment card code list.

Can have values specified in the payment card code list.

Example: mastercard

hide
string, optional

A single code or a list of codes for payment methods that should be excluded from the payment form for the payment (details). If a list of codes is specified, they should be separated by commas.

Can have values specified in the payment method code list.

Codes of payment methods that should be excluded from the payment form for the payment (details); codes from the payment method code list should be separated by commas.

Example: card, cup-union

identify_doc_number
string, optional

The identifier of the document serving as a proof of identity for the customer.

May be required for specific payment methods and can consist of a personal identity number (e.g., Trustly), a taxpayer number (e.g., PIX), or other similar identifiers.

Example: 6543234567

interface_type
string, optional

An identifier for the interface of the payment platform.

Using this parameter requires case-by-case coordination with ecommpay.

Example: {"id":7}

language_code
string, optional

The code of the language in which the payment form should be displayed (see this article).

Can consist of a two-letter ISO 639-1 alpha-2 code (see Language codes) or a code in a different format when this has been arranged prior.

Example: de

merchant_callback_url
string, optional

URL for handling request callbacks.

This parameter should be passed when callbacks for a request need to be sent to an address that is different from that specified by default (for information about callbacks and how to use them, see this article).

Example: https://cosmoshop.earth/specialorder

merchant_data
string, optional

Additional information that needs to be tracked by the web service (see this article).

The data that is passed in this parameter can vary. However, what data set is passed in this parameter should be communicated to the ecommpay specialists and configured beforehand to ensure the data is processed and displayed correctly in callbacks and payment information tabs (see this article). In specific cases can contain a JSON object; then, the " character (quotation mark, U+0022) needs to be preceded by the \ escape character (reverse solidus, U+005C) in order to be sent via a POST request. If the JSON object is passed via a GET request, escape characters are not required.

Figure 11. Example JSON object for a GET request, no escape characters
"merchant_data": "{"items":[{"sku":"GM12-CC",
        "description":"10 Copper Coins","count":1},
        {"sku":"GM12-GC","description":"Golden Coin",
        "count":2}],"total_count":3,"user_id":"122"}"
Figure 12. Example JSON object for a POST request, with escape characters
"merchant_data": "{\"items\":[{\"sku\":\"GM12-CC\",
        \"description\":\"10 Copper Coins\",\"count\":1},
        {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\",
        \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}"

merchant_fail_enabled
integer, optional

Indicator that specifies the availability options for the final redirection of the customer to the web service when a purchase is declined. (see this article):

Can have one of the following values:

  • 0—redirection to the web service is not available,
  • 1—redirection to the web service is available if Payment Page is opened in a separate browser tab (in this case, how the web service page is opened is determined by the corresponding parameter from the mode group) and not as an iframe object or in a modal window,
  • 2—redirection to the web service is available by default, using the mode specified in the mode parameter groupmode available by default.

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: 2

merchant_fail_redirect_mode
string, optional

Indicator that specifies the mode for the final redirection of the customer to the web service when a purchase is declined. (see this article):

Can have one of the following values:

  • iframe—opens the page in an iframe object (this value is ignored if the payment form is opened in a new tab and the customer is redirected in that new tabwhen applicable),
  • parent_page—opens the page in the currently active tab,
  • blank_page—opens the page in a new tab.

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: blank_page

merchant_fail_url
string, optional

URL for final redirection to the web service by customer decision when a purchase is declined (see this article).

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: https://cosmoshop.jupiter.example/pages/failed

merchant_return_enabled
integer, optional

Indicator that specifies the availability options for the preliminary redirection of the customer to the web service from the payment form. (see this article):

Can have one of the following values:

  • 0—redirection to the web service is not available,
  • 1—redirection to the web service is available only if Payment Page is opened in a separate browser tab (in this case, how the web service page is opened is determined by the corresponding parameter from the mode group) and not as an iframe object or in a modal window,
  • 2—redirection to the web service is available by default, using the mode specified in the mode parameter groupmode available by default.

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: 0

merchant_return_redirect_mode
string, optional

Indicator that specifies the mode for the preliminary redirection of the customer to the web service from the payment form. (see this article):

Can have one of the following values:

  • iframe—opens the page in an iframe object (this value is ignored if the payment form is opened in a new tab and the customer is redirected in that new tabwhen applicable),
  • parent_page—opens the page in the currently active tab,
  • blank_page—opens the page in a new tab.

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: iframe

merchant_return_url
string, optional

URL for preliminary redirection to the web service from the payment form (see this article).

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: https://cosmoshop.jupiter.example/return

merchant_success_enabled
integer, optional

Indicator that specifies the availability options for the final redirection of the customer to the web service when the purchase is completed. (see this article):

Can have one of the following values:

  • 0—redirection to the web service is not available,
  • 1—redirection to the web service is available if Payment Page is opened in a separate browser tab (in this case, how the web service page is opened is determined by the corresponding parameter from the mode group) and not as an iframe object or in a modal window,
  • 2—redirection to the web service is available by default, using the mode specified in the mode parameter groupmode available by default.

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: 1

merchant_success_redirect_mode
string, optional

Indicator that specifies the mode for the final redirection of the customer to the web service when the purchase is completed. (see this article):

Can have one of the following values:

  • iframe—opens the page in an iframe object (this value is ignored if the payment form is opened in a new tab and the customer is redirected in that new tabwhen applicable),
  • parent_page—opens the page in the currently active tab,
  • blank_page—opens the page in a new tab.

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: parent_page

merchant_success_url
string, optional

URL for final redirection to the web service by customer decision when the purchase is completed (see this article).

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: https://cosmoshop.jupiter.example/pages/success

mode
string, optional

Indicator that specifies the Payment Page operation mode.:

Can have one of the following values:

  • purchase—for making a purchase in Purchase mode (used by default),
  • payout—for making a payout in Payout mode,
  • card_verify—for verifying the validity of a payment instrument in Card Verify mode,
  • card_tokenize—for creating a payment detailscredentials token in Card Tokenize mode.

Example: card_verify

moto_type
integer, optional

Type of order for carrying out a Mail Order/Telephone Order an MO/TO purchase (involving the owner of the payment card providing its details over phone, mail, fax, or email):

  • 1—Mail Order,
  • 2—Telephone Order.

Example: 2

operation_type
string, optional

Indicator that specifies whether a the type of purchase made using a payment card is processed in one or two steps. with the 5th generation of Payment Page:

Should be specified in cases where the intended payment type is different from the one specified by default (with regard to the number of steps). Can have one of the following values:

  • sale—for one-step purchases (with the funds transferred to the merchant immediately; details),
  • auth—for two-step purchases (with the funds transferred to the merchant after first being in an authorisation hold; details).

Can be used for the 5th generation of Payment Page.

Should be specified in cases where the intended payment type is different from the one specified by default.

Example: auth

payment_amount
integer, required*

The amount of the payment in the smallest currency unit.

Specified in the smallest currency unit without a decimal separator. Required for all Payment Page modes except Card Tokenize.

Not required for Card Tokenize mode.

Example: 1815 (represents an amount of 18.15 currency units when referring to a currency with two decimals)

payment_currency
string, required*

Three-letter code of the payment currency.

The payment currency code (in the ISO-4217 alpha-3 format, according to the currency codes reference).

Specified in the ISO-4217 alpha-3 format, according to the currency codes reference. Required for all Payment Page modes except Card Tokenize.

Example: EUR

payment_description
string, optional

A short description for the payment, at most 255 characters longintended to be displayed to the customer, as well as being used by the web service for tracking purposes.

The length of the string cannot be more than 255 characters. Can be displayed to the customer on the information page, or via system notifications and the Dashboard interface.

Example: Thai massage session

payment_extra_param
string, optional

Additional relevant information pertaining to the payment.

May be required for specific payment methods (e.g., Trustly) and in other individual cases. Generally, where and how this parameter is used, as well as the format of any data contained therein should be decided upon during the integration of the web service, or when implementing additional payment methods or capabilities in advance.

payment_id
string, required*

The payment identifier assigned within the project; at most 255 characters long, case-insensitive.

Must be assigned by the web service. Should consist of a string no longer than 255 characters, be case-insensitive, and correspond one-to-one with the relevant payment within that project. Required for all Payment Page modes except Card Tokenize.

Example: payment_443

payment_merchant_risk
string, optional

Additional information about a purchase made for goods or services by a customer and about which 3‑D Secure authentication method is preferred by the merchant (see this article).

Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme. When the parameter is passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer (i.e., authentication via the frictionless flow instead of the challenge flow; details).

Figure 13. Example JSON object
{ 
  "payment":{ 
    "reorder":"01",
    "preorder_purchase":"01",
    "preorder_date":"11-10-2022",
    "challenge_indicator":"01",
    "challenge_window":"01",
    "gift_card":{ 
      "amount":12345,
      "currency":"USD",
      "count":1
    }
  }
}
Figure 14. Example resulting string
eyAKICAicGF5bWVudCI6eyAKICAgICJyZW9yZGVyIjoiMDEiLAogICAgInByZW9yZGVyX3B1cmNoYXNlIjoiMDEiLAogICAgInByZW9yZGVyX2RhdGUiOiIxMS0xMC0yMDIyIiwKICAgICJjaGFsbGVuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgImNoYWxsZW5nZV93aW5kb3ciOiIwMSIsCiAgICAiZ2lmdF9jYXJkIjp7IAogICAgICAiYW1vdW50IjoxMjM0NSwKICAgICAgImN1cnJlbmN5IjoiVVNEIiwKICAgICAgImNvdW50IjoxCiAgICB9CiAgfQp9==

payment_methods_options
string, optional

Additional information relevant for specific payment methods and third-party services.

Can be used to manage individual methods, including Open Banking methods, in order to send additional information about the customer and the payment, manage the page size of third-party web services that the customer is redirected to, and for other possible reasons, depending on the specific payment methods being used.

Example: {\"online_thailand_banks\": {\"split_banks\": true}}

project_id
integer, required

Identifier of the project intended to manage the interactions of the web service with the payment platform. This identifier is, assigned by ecommpay during the integration (details).

Example: 57123

receipt_data
string, optional

Information about line items in an order (see this article).

Can be used to generate a document to be sent to the customer (see this article). Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.

Figure 15. Example JSON object
{  
   "receipt_data":{  
      "positions":[  
         {  
            "quantity":3,
            "amount":10000,
            "tax":18,
            "tax_amount":1800,
            "description":"Design frame"
         }
      ],
      "total_tax_amount":1800,
      "common_tax":18       
   }
}
Figure 16. Example resulting string
receipt_data: "eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAg
ICAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMCwKICAgICAgICAgICAgInRheCI
6MTgsCiAgICAgICAgICAgICJ0YXhfYW1vdW50IjoxODAwLAogICAgICAgICAgICAiZGVzY3JpcHRpb24iOiJEZXN
pZ24gZnJhbWUiCiAgICAgICAgIH0KICAgICAgXSwKICAgICAgInRvdGFsX3RheF9hbW91bnQiOjE4MDAsCiAgICA
gICJjb21tb25fdGF4IjoxOCAgICAgICAKfQ"

recipient_address
string, optional

The name of the street and the house number (including any additional parts of the address such as building indicators and apartment numbers) in the address of the payment recipient, at most 99 characters long.

The length of the string cannot be more than 99 characters.

Example: Via Dietro Duomo 36

recipient_card_holder
string, optional

The first and last names of the holder of the payment card used to receive the payment, at most 255 characters long.

Should be spelled as specified on the card and adhere to the rules for specifying names (see this article). The length of the string cannot be more than 255 characters.

Example: Fran Petrarca

recipient_city
string, optional

The name of the place of residence (e.g., town, city, or other settlement type) in the address of the payment recipient, at most 25 characters long.

The length of the string cannot be more than 25 characters.

Example: Padova

recipient_country
string, optional

The country code of the place of residence of the payment recipient (in the ISO 3166-1 alpha-2 format).

Specified in the ISO 3166-1 alpha-2 format.

Example: IT

recipient_first_name
string, optional

The name of the payment recipient, at most 255 characters.

The length of the string cannot be more than 255 characters.

Example: Fran

recipient_last_name
string, optional

The last name of the payment recipient, at most 255 characters.

The length of the string cannot be more than 255 characters.

Example: Petrarca

recipient_pan
string, optional

The number of the payment card used to receive the payment.

Specified as is, without masked characters, spaces, or other separators.

Example: 4314220000000056

recipient_state
string, optional

The local code of the region (state, province, or other administrative subdivision type) of the payment recipient's address.

The value of this parameter is the second element of a code for a subdivision (in ISO 3166-2), without the two-letter country code and the hyphen-minus used as a separator. Should be specifiedSpecified when the recipient_country parameter is also specified in the same query.

Example: 52 (when specified for Tuscany, designated IT‑52)

recipient_wallet_id
string, optional

The identifier of the digital wallet used by the payment recipient, at most 64 characters.

The length of the string cannot be more than 64 characters. Specified as is, without masked characters, spaces, or other separators.

Example: WID20071304

recipient_wallet_owner
string, optional

The first and last names of the owner of the digital wallet used by the payment recipient, at most 255 characters in total.

Should be spelled the same way as in the payment system and be at most 255 characters long in total.

Example: Fran Petrarca

recurring
string, optional

Information about the COF purchase being registered (details).

If the ecommpay JavaScript library is used, can be passed as a JSON object, otherwise should be specified as a URL obtained by encoding the source JSON object.

Figure 17. Example JSON object
{
    "register": true,
    "type": "U"
}
Figure 18. Example resulting string
%7B%22register%22%3Atrue%2C%22type%22%3A%22U%22%7D%2C

recurring_register
integer, optional

Indicator specifying whether a COF purchase should be registered, using the information passed in the recurring parameter (see this article).:

Can have one of the following values:

  • 0—the COF purchase should not be registeredshouldn't be,
  • 1—the COF purchase should be registeredshould be.

If the merchant.js library is used (details), this parameter can be specified as a boolean value and set to either false or true.

Example: 1

redirect
integer (boolean*), optional

Indicator specifying whether the payment form should be opened on a new HTML page regardless of the type of device being used (see this article).:

Can have one of the following values:

  • 0—the payment form should be opened using either the default method or a different method specified in other parameters,
  • 1—the payment form should be opened in a new HTML page.

If the merchant.js library is used (details), this parameter can be specified as a boolean value and set to either false or true.

Example: 1

redirect_fail_mode
string, optional

Indicator that specifies the mode for the final redirection of the customer to the web service when the purchase is declined (see this article):.

Can have one of the following values:

  • iframe—opens the page in an iframe object (this value is ignored if the payment form is opened in a new tab and the customer is redirected in that new tabwhen applicable),
  • parent_page—opens the page in the currently active tab,
  • blank_page—opens the page in a new tab.

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: blank_page

redirect_fail_url
string, optional

URL for final redirection to the web service if the purchase is declined (see this article).

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: https://cosmoshop.jupiter.example/pages/failed

redirect_on_mobile
integer (boolean*), optional

Indicator specifying whether the payment form should be opened on a new HTML page for mobile devices (see this article).:

Can have one of the following values:

  • 0—the payment form should be opened using either the default method or a different method specified in other parameters,
  • 1—the payment form should be opened in a new HTML page.

If the merchant.js library is used (details), this parameter can be specified as a boolean value and set to either false or true.

Example: 1

redirect_success_mode
string, optional

Indicator that specifies the mode for the final redirection of the customer to the web service when the purchase is completed (see this article):.

Can have one of the following values:

  • iframe—opens the page in an iframe object (this value is ignored if the payment form is opened in a new tab and the customer is redirected in that new tabwhen applicable),
  • parent_page—opens the page in the currently active tab,
  • blank_page—opens the page in a new tab.

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: parent_page

redirect_success_url
string, optional

URL for final redirection to the web service by customer decision when a purchase is completed (see this article).

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: https://cosmoshop.jupiter.example/pages/success

redirect_return_url
string, optional

URL for preliminary redirection to the web service from third-party services such as banks and other payment systems (see this article).

Requires this functionality (for specific third-party services) to be set up and enabled beforehand. For more information about managing options for redirecting the customer back to the web service, see this article.

Example: https://cosmoshop.jupiter.example/pages/third_party_services

redirect_tokenize_mode
string, optional

Indicator that specifies the mode for the automatic final redirection of the customer to the web service when a token has been generated in Card Tokenize mode using the relevant payment details (see this article):.

Can have one of the following values:

  • iframe—opens the page in an iframe object (this value is ignored if the payment form is opened in a new tab and the customer is redirected in that new tabwhen applicable),
  • parent_page—opens the page in the currently active tab.

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: parent_page

redirect_tokenize_url
string, optional

URL for automatic final redirection to the web service when a token has been generated in Card Tokenize mode using the relevant payment details (see this article).

For more information about managing options for redirecting the customer back to the web service, see this article.

Example: https://cosmoshop.jupiter.example/pages/tokenize

region_code
string, optional

The country code for the customer's address (in the ISO 3166-1 alpha-2 format).

Specified in the ISO 3166-1 alpha-2 format. If this parameter is not specified, the country code is determined using the customer's IP address or other parameters.

Example: FR

sender_address
string, optional

The name of the street and the house number (including any additional parts of the address such as building indicators and apartment numbers) in the address of the payment sender, at most 99 characters long.

The length of the string cannot be more than 99 characters.

Example: Via Certaldo 18

sender_city
string, optional

The name of the place of residence (e.g., town, city, or other settlement type) in the address of the payment sender, at most 25 characters long.

The length of the string cannot be more than 25 characters.

Example: Florence

sender_country
string, optional

The code of the country in the address of the payment sender (in the ISO 3166-1 alpha-2 format).

Specified in the ISO 3166-1 alpha-2 format.

Example: IT

sender_first_name
string, optional

The first name of the payment sender, at most 255 characters long.

The length of the string cannot be more than 255 characters.

Example: Gio

sender_last_name
string, optional

The last name of the payment sender, at most 255 characters long.

The length of the string cannot be more than 255 characters.

Example: Boccaccio

sender_state
string, optional

The local code of the region (state, province, or other administrative subdivision type) of the payment sender's address.

The value of this parameter is the second element of a code for a subdivision (in ISO 3166-2), without the two-letter country code and the hyphen-minus used as a separator. Should be specified when the sender_country parameter is also specified in the same query.

The local code of the region of the payment sender's address.

Example: 52 (when specified for Tuscany, designated IT‑52)

sender_wallet_id
string, optional

The identifier of the digital wallet used by the payment sender, at most 64 characters long.

The length of the string cannot be more than 64 characters. Specified as is, without masked characters, spaces, or other separators.

Example: WID16061313

sender_zip
string, optional

The postal code in the address of the payment sender.

The length of the string cannot be more than 255 characters.

Example: 50142

signature
string, required

The digital signature used to sign the query parameters (see this article).

Should be generated using the appropriate algorithm after all relevant parameters have been specified (see this article).

style_id
integer, optional

The identifier of the payment form design style.

Can be used for the 5th generation Payment Page design style (see this article).

The identifier of a 5th generation payment form design style (see this article).

Example: 6123

target_element
string, optional

The iframe element identifier (for the HTML page of the web service) of the element where the payment form should be opened for opening the payment form (see this article).

Example: widget-container

terminal_id
integer, optional

The identifier of the payment form terminal.

Can be used for the 4th generation Payment Page design style or earlier (see this article).

The identifier of a 4th generation payment form design style or earlier (see this article).

Example: 54

uuid
string, optional

Identifier used for internal purposes.

The length of the string cannot be more than 64 characters. Can be used to invoke the payment form in Payout mode by specifying the value received in the payout registration callback (see this article).

Example: Lm3V9lmykig2d51Z/2Yrnue9+o5GTkVvY/sRDLKAnSS+AagnGCJ1nsPg==