# Payment Page API specification {#en_PP_Parameters}

An API specification with the description of data structures used in requests for opening Payment Page.

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 callsintended 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 in 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](en_pp_3ds.md#)\) and having to provide [additional payment information](en_pp_clarification.md), 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](en_PP_Payment_by_token.md)\).

 Example: `42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021`

|
|`avs_post_code`  
 string, optional

|The postal code of the customer to be used in the [Address Verification Service](en_PP_avs.md) check.

 Example: `WS13 6LG`

|
|`avs_street_address`  
 string, optional

|The address of the customer to be used in the [Address Verification Service](en_PP_avs.md) 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 whena 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 action \(see [this article](en_pp_time_limit.md)\).

 Should be specified as follows: `YYYY-MM-DDThh:mm:ss`±`hh` or `YYYY-MM-DDThh:mm:ss`±`hh:mm`. The time allocated for working with the form cannot exceed 30 days from the moment when the request for opening Payment Page was sent.

 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\) andthe name of the street 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](en_pp_3ds.md#)\).

 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](en_pp_3ds.md#)\).

 Example: `London`

|
|`billing_country`  
 string, optional

|The country code in the customer's billing address.

 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](en_pp_3ds.md#)\).

 Pattern: `^[A-Z]{2}$`.

 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](en_pp_3ds.md#)\).

 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](en_pp_3ds.md#)\).

 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](en_pp_3ds.md#)\).

 Pattern: `^[0-9A-Z]{1,3}$`.

 Example: `DOR`

|
|`booking_info`  
 string, optional

|Booking information tracked by the web service.

 Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.The JSON object can include various combinations of elements from the list of supported data. Can be used to record and track relevant data about payments rendered for services by various organisations \(see [this article](en_pp_additional_data.md#)\).

 -   `bookers`, array—the array with the information about the customers for whom the service is booked. Each element of this array contains:
    -   `first_name`, string—the name of the customer provided at the time of booking
    -   `last_name`, string—the last name of the customer provided at the time of booking
    -   `email`, string—the email provided at the time of booking
-   `items`, array—the array with the information about separate services included in the booking. Each element of this array contains:
    -   `description`, string—description of the service included in the booking
    -   `start_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—starting date of the service included in the booking
    -   `end_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—ending date of the service included in the booking
-   `start_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—starting date of the booked service
-   `end_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—ending date of the booked service
-   `description`, string—a free-form description of the booked service
-   `total`, integer—the total cost of the booking
-   `pax`, integer—the number of people per booking
-   `reference`, string—the booking reference, which can be the URL, the name of the booked service, or its code in the merchant web service
-   `id`, string—the identifier of the booking, unique in the merchant web service

 ``` {#codeblock_t2l_mzm_phc .language-json}
"booking_info": {
  "start_date": "12-08-2026",
  "end_date": "14-08-2026",
  "description": "Sideris music festival full pass",
  "total": 200000,
  "pax": 2,
  "bookers": [
     {
        "first_name": "William",
        "last_name": "Herschel",
        "email": "rsfellow@mail.com"
     },
     {
        "first_name": "Caroline",
        "last_name": "Herschel",
        "email": "salariedastronomer@mail.com"
     }
  ],        
  "items":[
     {
        "description": "VIP Arrival",
        "start_date": "12-08-2026",
        "end_date": "12-08-2026"
     },
     {
        "description": "Hotel",
        "start_date": "12-08-2026",
        "end_date": "14-08-2026"
     },
     {
        "description": "Concerts",
        "start_date": "12-08-2026",
        "end_date": "14-08-2026"
     },
     {
        "description": "VIP Departure",
        "start_date": "14-08-2026",
        "end_date": "14-08-2026"
     }
  ],
  "reference": "musicfestlink",
  "id": "83"
}
```

 ``` {#codeblock_gt2_yzm_phc}
ewogICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAiZGVzY3JpcHRpb24iOiAiU2lkZXJpcyBtdXNpYyBmZXN0aXZhbCBmdWxsIHBhc3MiLAogICJ0b3RhbCI6IDIwMDAwMCwKICAicGF4IjogMiwKICAiYm9va2VycyI6IFsKICAgICB7CiAgICAgICAgImZpcnN0X25hbWUiOiAiV2lsbGlhbSIsCiAgICAgICAgImxhc3RfbmFtZSI6ICJIZXJzY2hlbCIsCiAgICAgICAgImVtYWlsIjogInJzZmVsbG93QG1haWwuY29tIgogICAgIH0sCiAgICAgewogICAgICAgICJmaXJzdF9uYW1lIjogIkNhcm9saW5lIiwKICAgICAgICAibGFzdF9uYW1lIjogIkhlcnNjaGVsIiwKICAgICAgICAiZW1haWwiOiAic2FsYXJpZWRhc3Ryb25vbWVyQG1haWwuY29tIgogICAgIH0KICBdLCAgICAgICAgCiAgIml0ZW1zIjpbCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgQXJyaXZhbCIsCiAgICAgICAgInN0YXJ0X2RhdGUiOiAiMTItMDgtMjAyNiIsCiAgICAgICAgImVuZF9kYXRlIjogIjEyLTA4LTIwMjYiCiAgICAgfSwKICAgICB7CiAgICAgICAgImRlc2NyaXB0aW9uIjogIkhvdGVsIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxMi0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9LAogICAgIHsKICAgICAgICAiZGVzY3JpcHRpb24iOiAiQ29uY2VydHMiLAogICAgICAgICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICAgICAgICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IgogICAgIH0sCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgRGVwYXJ0dXJlIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9CiAgXSwKICAicmVmZXJlbmNlIjogIm11c2ljZmVzdGxpbmsiLAogICJpZCI6ICI4MyIKfQ==
```

|
|`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](en_faq_payment_processing.md#section_dbx_kby_t1c)\).

 Pattern: `^[\p\{L}\p\{M}\s\-\'.]{1,255}$`.

 Example: `John Doe`

|
|`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](en_PP_method_ModalWindow.md#).

 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](en_pp_interaction_organisation.md#)\), 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](en_PP_Gathering_customer_data.md)\).

 Example: `Main Street, 12`

|
|`customer_account_info`  
 string, optional

|Information about the customer's account and contact detailsobtained by the web service.

 Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.The JSON object can include the `customer` object containing various combinations of elements from the list of supported data. 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](en_pp_3ds.md#)\).

 -   `address_match`, string—indicates whether the customer's billing address matches the address specified in the `shipping` object:
    -   `Y`—addresses match
    -   `N`—addresses do not match
-   `home_phone`, string—the customer's home phone number, contains between 4 and 24 digits
-   `work_phone`, string—the customer's work phone number, contains between 4 and 24 digits
-   `account`, object—the object with the customer's account information kept on file by the merchant:
    -   `activity_day`, integer—number of payment attempts in the last 24 hours, 3 characters maximum
    -   `activity_year`, integer—number of payment attempts in the last 365 days, 3 characters maximum
    -   `additional`, string—additional information about the customer's account in free text, for example, its identifier. Can contain up to 64 characters
    -   `age_indicator`, string, `^0[1-5]$`—number of days since the customer account was created. Possible values:
        -   `01`—guest checkout
        -   `02`—the account was created at the moment of making a payment
        -   `03`—fewer than 30 days
        -   `04`—between 30 and 60 days
        -   `05`—more than 60 days
    -   `auth_data`, string—additional login information in free text, can contain up to 255 characters
    -   `auth_method`, string, `^(0[1-4]|0[1-4][1-6])$`—indicates how the customer was authenticated during their most recent login to the web service. Can have one of the possible values:
        -   for standard card payments:
            -   `01`—no authentication
            -   `02`—logging in with authentication data kept on file by the merchant
            -   `03`—logging in with the federated identity credentials \(for example, Google Account or Facebook ID\)
            -   `04`—logging in with the use of FIDO authenticator \(Fast Identity Online\)
    -   `auth_time`, string, `^\\d{2}-\\d{2}-\\d{4}\\d{2}:\\d{2}$`—date and time of the customer's most recent account login in the `DD-MM-YYYYhh:mm` format
    -   `change_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—date of the most recent change to the account, except for the password change or password reset, in the `DD-MM-YYYY` format
    -   `change_indicator`, string, `^0[1-4]$`—number of days since the most recent change to the account, except for the password change or password reset. Possible values:
        -   `01`—the account was updated on the day when the payment was made
        -   `02`—fewer than 30 days
        -   `03`—between 30 and 60 days
        -   `04`—more than 60 days
    -   `date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—the account creation date in the `DD-MM-YYYY` format
    -   `pass_change_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—date of the most recent password change or reset in the `DD-MM-YYYY` format
    -   `pass_change_indicator`, string, `^0[1-5]$`—number of days since the most recent password change or reset. Possible values:
        -   `01`—password was not changed or reset
        -   `02`—password was changed or reset on the day when the payment was made
        -   `03`—fewer than 30 days
        -   `04`—between 30 and 60 days
        -   `05`—more than 60 days
    -   `payment_age`, string, `^\\d{2}-\\d{2}-\\d{4}$`—card record creation date in the `DD-MM-YYYY` format
    -   `payment_age_indicator`, string, `^0[1-5]$`—number of days since the payment card details were saved to a customer's account. Possible values:
        -   `01`—guest checkout
        -   `02`—card details were saved on the day when the payment was made
        -   `03`—fewer than 30 days
        -   `04`—between 30 and 60 days
        -   `05`—more than 60 days
    -   `provision_attempts`, integer—number of attempts to save new card details to a customer's account in the last 24 hours, 3 characters maximum
    -   `purchase_number`,—number of purchases made via the customer's account in the last 6 months, 4 characters maximum
    -   `suspicious_activity`, string, `^0[1-2]$`— indicates the presence of suspicious activity. Possible values:
        -   `01`—no suspicious activity detected
        -   `02`—suspicious activity detected

 ```language-json
{ 
  "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"
    }
  }
}
```

 ```
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](pm_neteller.md#) and [OVO Wallet](pm_ovo.md#)\). 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](en_PP_Gathering_customer_data.md)\).

 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](en_PP_Gathering_customer_data.md)\).

 Example: `London`

|
|`customer_country`  
 string, optional

|The country code in the customer's address.

 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](en_PP_Gathering_customer_data.md)\).

 Pattern: `^[A-Z]{2}$`.

 Example: `GB`

|
|`customer_day_of_birth`  
 string, optional

|The date of birth of the customer.

 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](en_PP_Gathering_customer_data.md)\).

 Pattern: `^\\d{2}-\\d{2}-\\d{4}$`.

 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](en_PP_Gathering_customer_data.md)\).

 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](en_PP_Gathering_customer_data.md)\).

 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](en_PP_Gathering_customer_data.md)\).

 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](en_PP_Gathering_customer_data.md)\).

 Example: `Mary`

|
|`customer_mpi_result`  
 string, optional

|Information about the customer's most recent authentication via the 3‑D Secure protocol.

 Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.The JSON object can include various combinations of elements from the list of supported data. 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](en_pp_3ds.md#)\).

 -   `mpi_result`, object—object that contains information about the previous authentication attempt of the customer:
    -   `acs_operation_id`, string, `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$`—the identifier that the issuer assigned to the previous operation of the customer and returned in the `acs_operation_id` parameter of the callback with payment processing result. Can contain up to 36 characters.
    -   `authentication_flow`, string, `^0[1-2]$`—the flow used by the issuer to authenticate the cardholder when processing the previous operation. It is a value of the `authentication_flow` parameter returned in the callback with payment processing result.

Possible values:

        -   `01`—frictionless flow
        -   `02`—challenge flow
    -   `authentication_timestamp`, string, `^\\d{12}$`—date and time of the previous successful customer authentication as returned in the `mpi_timestamp` parameter of the callback with payment processing result.

 ```language-json
{ 
  "customer":{ 
    "mpi_result":{ 
      "acs_operation_id":"00000000-0005-5a5a-8000-016d3ea31d54",
      "authentication_flow":"01",
      "authentication_timestamp":"202210111050"
    }
  }
}
```

 ```
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAibXBpX3Jlc3VsdCI6eyAKICAgICAgImFjc19vcGVyYXRpb25faWQiOiIwMDAwMDAwMC0wMDA1LTVhNWEtODAwMC0wMTZkM2VhMzFkNTQiLAogICAgICAiYXV0aGVudGljYXRpb25fZmxvdyI6IjAxIiwKICAgICAgImF1dGhlbnRpY2F0aW9uX3RpbWVzdGFtcCI6IjIwMjIxMDEwMTA1MCIKICAgIH0KICB9Cn0===
```

|
|`customer_phone`  
 string, optional

|The phone number of the customer.

 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](en_PP_Gathering_customer_data.md)\).

 Pattern: `^[0-9]{4,24}$`.

 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.

 Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.The JSON object can include various combinations of elements from the list of supported data. 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](en_pp_3ds.md#)\).

 -   `shipping`, object—object with shipping details:
    -   `address`, string—shipping address, can contain up to 150 characters.
    -   `address_usage`, string, `^\\d{2}-\\d{2}-\\d{4}$`—date when the specified shipping address was used for the first time, in the `DD-MM-YYYY` format.
    -   `address_usage_indicator`, string, `^0[1-4]$`—number of days since the specified shipping address was used for the first time. Possible value:
        -   `01`—first-time use
        -   `02`—fewer than 30 days
        -   `03`—between 30 and 60 days
        -   `04`—more than 60 days
    -   `city`, string—shipping city, can contain up to 50 characters.
    -   `country`, string, `^[A-Z]{2}$`—shipping country code in the ISO 3166-1 alpha-2 format.
    -   `delivery_email`, string—the email to deliver purchased digital content to if the customer chooses email delivery. Can contain up to 255 characters.
    -   `delivery_time`, string, `^0[1-4]$`—delivery time. Possible values:
        -   `01`—digital same day delivery
        -   `02`—same day delivery
        -   `03`—next day delivery
        -   `04`—delivery more than one day after the purchase was made
    -   `name_indicator`, string, `^0[1-2]$`—indicates whether the customer's name matches the recipient's name. Possible values:
        -   `01`—names match
        -   `02`—names do not match
    -   `postal`, string—shipping postal code, can contain up to 16 characters.
    -   `region`, string—the name of the region \(state, province, or other administrative subdivision type\) of the shipping address. Can contain up to 255 characters.
    -   `region_code`, string, `^[0-9A-Z]{1,3}$`—state, province, or region code in the ISO 3166-2 format, for example, `DOR` for Dorset.

If you specify this parameter, you also need to specify and populate the `country` parameter in the `shipping` object.

    -   `type`, string, `^0[1-7]$`—delivery option selected by the customer. Possible values:
        -   `01`—delivery to the cardholder's billing address
        -   `02`—delivery to a different verified address
        -   `03`—delivery to the address that is not verified and does not match the billing address
        -   `04`—store delivery
        -   `05`—digital delivery
        -   `06`—no delivery needed \(for example, event ticket purchase\)
        -   `07`—other

 ```language-json
{ 
  "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":"Vilnius County",
      "region_code":"LND",
      "name_indicator":"01"
    }
  }
}
```

 ```
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](en_PP_Gathering_customer_data.md)\).

 Example: `1984`

|
|`customer_state`  
 string, optional

|The name of the region\(state, province, or other administrative subdivision type\) of 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](en_PP_Gathering_customer_data.md)\).

 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](en_PP_Gathering_customer_data.md)\).

 Example: `Main`

|
|`customer_zip`  
 string, optional

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

 The length of the string cannot be more than 10 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](en_PP_Gathering_customer_data.md)\).

 Example: `75001`

|
|`debt_account`  
 string, optional

|The number of the account designated to receive funds as part of debt settlement purchases.

 This parameter is required for debt settlement purchases \(see [this article](en_PP_debt_repayments.md)\).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](en_PP_pm_redirect_mode.md)\).

 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](en_pp_interaction_organisation.md#)\), 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](en_PP__PreselectingPS.md)\).

 Can have values specified in the [payment method code list](en_pm_codes.md).

 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](en_PP__PreselectingPS.md)\).

 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.

 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](en_PP__PreselectingPS.md)\).

 Can have values specified in the [payment card code list](en_card_codes.md).

 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](en_pp_methods_availability.md#)\). If a list of codes is specified, they should be separated by commas.

 Can have values specified in the [payment method code list](en_pm_codes.md).

 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, a taxpayer number\(e.g., [PIX](pm_pix.md#)\), 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](en_PP_WigetLanguages.md#section_ivb_h3b_sqb)\) and the notifications should be generated \(see [this article](en_PP_receipt_data.md)\).

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

 Pattern: `/^([a-z]{2}|zh\-hant)$/i`.

 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](en_platform_callbacks.md#)\).

 Example: `https://cosmoshop.earth/specialorder`

|
|`merchant_data`  
 string, optional

|Additional information that needs to be tracked by the web service.

 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](en_pp_additional_data.md#)\). 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.

 ``` {#codeblock_jjf_xhb_d2c .language-json}
"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"}"
```

 ``` {#codeblock_ts4_xhb_d2c .language-json}
"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_descriptor`   
 string, optional

|Information about the merchant provided to other parties involved in card payment processing and subsequently to customers.

 Can be used for processing purchases and performing payment instrument verification. The length of the string is limited to 22 characters for cards of the Mastercard card network and 25 characters for cards of the Visa card network. For more information on working with this parameter, see [this article](en_pp_descriptor.md).

 Example: `Cosmotour* to the Moon`

|
|`merchant_domain`  
 string, optional

|The domain name of the web service where the payment form should be opened.

 This parameter should be passed when Payment Page is invoked in the form of embedded Apple Pay and Google Pay payment buttons \(see [this article](en_pp_embedded_payment_buttons.md#)\).

 Example: `merchant.example.com`

|
|`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.

 Can have one of the following values:

 -   `0`—redirectionto the web service is not available,
-   `1`—redirectionto 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`—redirectionto the web service is available by default, using the mode specified in the `mode` parameter group.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 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.

 Can have one of the following values:

 -   `iframe`—opens the pagein 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 tab\),
-   `parent_page`—opens the pagein the currently active tab,
-   `blank_page`—opens the pagein a new tab.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 Example: `blank_page`

|
|`merchant_fail_url`  
 string, optional

|URL for final redirection to the web service by customer decision when a purchase is declined.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 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.

 Can have one of the following values:

 -   `0`—redirectionto the web service is not available,
-   `1`—redirectionto 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`—redirectionto the web service is available by default, using the mode specified in the `mode` parameter group.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 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.

 Can have one of the following values:

 -   `iframe`—opens the pagein 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 tab\),
-   `parent_page`—opens the pagein the currently active tab,
-   `blank_page`—opens the pagein a new tab.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 Example: `iframe`

|
|`merchant_return_url`  
 string, optional

|URL for preliminary redirection to the web service from the payment form.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 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.

 Can have one of the following values:

 -   `0`—redirectionto the web service is not available,
-   `1`—redirectionto 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`—redirectionto the web service is available by default, using the mode specified in the `mode` parameter group.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 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.

 Can have one of the following values:

 -   `iframe`—opens the pagein 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 tab\),
-   `parent_page`—opens the pagein the currently active tab,
-   `blank_page`—opens the pagein a new tab.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 Example: `parent_page`

|
|`merchant_success_url`  
 string, optional

|URL for final redirection to the web service by customer decision when the purchase is completed.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 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 purchasein Purchase mode \(used by default\),
-   `payout`—for making a payoutin Payout mode,
-   `card_verify`—for verifying the validity of a payment instrumentin Card Verify mode,
-   `card_tokenize`—for creating a payment details tokenin Card Tokenize mode.

 Example: `card_verify`

|
|`moto_type`  
 integer, optional

|Type of order for carrying outa Mail Order/Telephone Order 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 specifieswhether a purchaseis processed in one or two steps.

 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](en_pp_purchase.md)\),
-   `auth`—for two-step purchases \(with the funds transferred to the merchant after first being in an authorisation hold;[details](en_pp_purchase_auth.md)\).

 Example: `auth`

|
|`payment_amount`  
 integer, required\*

|The amount of the paymentin the smallest currency unit.

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

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

|
|`payment_cryptocurrency_type` string, optional

|Indicator that specifies the type of the cryptocurrency.

 Required for payments involving cryptocurrencies via the Mastercard MoneySend and Visa Direct services. Can have one of the following values:

 -   `cbdc`—a central bank digital currency or tokenized deposit issued by a central bank, reserve bank, or other national monetary authority.
-   `stablecoins_fiat_backed`—a fiat-backed digital asset with reserves held by a licensed financial institution.
-   `native_tokens`—a digital currency native to a specific blockchain, required for transactions within its network, including fee payments.
-   `other`—a non-fiat digital asset that does not fit other types or cannot be classified at the time of transaction initiation.

 Example: `cbdc`

|
|`payment_currency`  
 string, required\*

|Three-letter code of the payment currency.

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

 Pattern: `^[A-Z]{3}$`.

 Example: `EUR`

|
|`payment_description`  
 string, optional

|A short description for the payment, intended 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 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 uponduring the integration of the web service, or when implementing additional payment methods or capabilities.

|
|`payment_id`  
 string, required\*

|The payment identifier.

 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.

 Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.The JSON object can include various combinations of elements from the list of supported data. When 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](en_pp_3ds.md#)\).

 -   `challenge_indicator`, string, `^0[1-9]$`—indicates whether the challenge flow is preferred. Possible values:
    -   `01`—no preferences
    -   `02`—not using the challenge flow is preferred
    -   `03`—using the challenge flow is preferred
    -   `04`—using the challenge flow is required
    -   `05`—do not use the challenge flow, the merchant has performed the risk analysis
    -   `06`—do not use the challenge flow, use the Data Only flow
    -   `07`—do not use the challenge flow, Strong Customer Authentication has been applied otherwise
    -   `08`—do not use the challenge flow, the merchant is included in cardholder's trusted beneficiaries list
    -   `09`—using the challenge flow is required, prompt the cardholder to add the merchant to the trusted beneficiaries list
-   `challenge_window`, string, `^0[1-5]$`—the dimensions of a window in which the authentication page opens. Possible values:
    -   `01`—250 x 400 px
    -   `02`—390 x 400 px
    -   `03`—500 x 600 px
    -   `04`—600 x 400 px
    -   `05`—full screen
-   `gift_card`, object—object with information about a purchase made with a prepaid or gift card:
    -   `amount`, integer—the amount of the purchase made with a prepaid or gift card in the smallest units of currency
    -   `count`, integer—total number of prepaid or gift cards used for making a purchase
    -   `currency`, string—the currency of the purchase made with a prepaid or gift card in the ISO 4217 alpha-3 format
-   `preorder_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—the date when the preordered merchandise or service will be available in the `DD-MM-YYYY` format
-   `preorder_purchase`, string, `^0[1-2]$`—indicates whether the purchase is a preorder. Possible values:
    -   `01`—not a preorder
    -   `02`—a preorder
-   `reorder`, string, `^0[1-2]$`—indicates whether the customer is buying the merchandise or the service for the first time or it is a repeat purchase. Possible values:
    -   `01`—first-time purchase
    -   `02`—repeat purchase

 ```language-json
{ 
  "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
    }
  }
}
```

 ```
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 projectintended to manage the interactions of the web service with the payment platform. This identifier is assigned by Ecommpayduring the integration \([details](en_glossary.md#)\).

 Example: `57123`

|
|`receipt_data`  
 string, optional

|Information about line items in an order.

 Can be used to generate a proof of purchase document to be sent to the customer \(see [this article](en_PP_receipt_data.md)\).Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.The JSON object can include various combinations of elements from the list of supported data.

 -   `positions`, array—array which allows listing up to 300 purchased items in the notification. For each listed item, the following information can be specified:
    -   `amount`, integer—the price of the item
    -   `quantity`, integer—the number of purchased items of the same kind
    -   `tax`, integer—the VAT rate if it differs for different listed items
    -   `tax_amount`, integer—the VAT amount
    -   `description`, string—the description of the purchased item.
-   `total_tax_amount`, integer—the total VAT amount for the entire purchase
-   `common_tax`, integer—the VAT rate if it is the same for all listed items

 ``` {#codeblock_vd1_r3b_d2c .language-json}
{  
   "receipt_data":{  
      "positions":[  
         {  
            "quantity":3,
            "amount":10000,
            "tax":18,
            "tax_amount":1800,
            "description":"Design frame"
         }
      ],
      "total_tax_amount":1800,
      "common_tax":18       
   }
}
```

 ``` {#codeblock_k1g_r3b_d2c}
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.

 The length of the string cannot be more than 99 characters.Required for Visa Direct debiting operations performed with Visa cards issued in Australia, Canada, or New Zealand.

 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.

 Should be spelled as specified on the card and adhere to the rules for specifying names \(see [this article](en_faq_payment_processing.md#section_dbx_kby_t1c)\). 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.

 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.

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

 Pattern: `^[A-Z]{2}$`.

 Example: `IT`

|
|`recipient_day_of_birth`  
 string, optional

|The date of birth of the payment recipient.

 Specified in `DD-MM-YYYY` format. Required if a Visa card is used to receive the payment.

 Pattern: `^\\d{2}-\\d{2}-\\d{4}$`.

 Example: `12-12-1990`

|
|`recipient_first_name`   
 string, optional

|The name of the payment recipient.

 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.

 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.

 Pattern: `^[0-9]{15,19}$`.

 Example: `4314220000000056`

|
|`recipient_state`   
 string, optional

|The local code of the region\(state, province, or other administrative subdivision type\) of the payout recipient's address \([details](en_Gate_payout.md)\).

 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 for processing payouts when the `recipient_country` parameter is also specified in the same query and its value is the country code of Canada \(`CA`\) or the United States \(`US`\).

 Pattern: `^[A-Z]+$`.

 Example: `AK`\(when specified for Alaska, designated `US-AK`\)

|
|`recipient_state_code`   
 string, optional

|The local code of the region\(state, province, or other administrative subdivision type\) associated with the recipient's address for fund transfers using Mastercard MoneySend and Visa Direct services \([details](en_gate_money_transfer_services.md#)\).

 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 for Mastercard MoneySend and Visa Direct operations when the `recipient_country` parameter is also specified in the same query and its value is the country code of Canada \(`CA`\) or the United States \(`US`\).

 Pattern: `^[A-Z]+$`.

 Example: `ON`\(when specified for Ontario, designated `CA-ON`\)

|
|`recipient_wallet_id`   
 string, optional

|The identifier of the digital wallet used by the payment recipient.

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

 Pattern: `^[^!@&~№{}|<>\\[\\]]*$`.

 Example: `WID20071304`

|
|`recipient_wallet_owner`   
 string, optional

|The first and last names of the owner of the digital wallet used by the payment recipient.

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

 Pattern: `/^[\p{L}\p{M}0-9 .'-]+$/u`.

 Example: `Fran Petrarca`

|
|`recurring`  
 string, optional

|Information about the COF purchase being registered \([details](en_pp_recurring.md)\).

 If the Ecommpay JavaScript library is used, can be passed as a JSON object\(containing various combinations of elements from the list of supported data\), otherwise should be specified as a URLobtained by encoding the source JSON object.

 -   `register`, boolean—indicator that specifies whether a COF purchase should be registered
-   `type`, string, `^[RCU]$`—type of the COF purchase to register, possible values:
    -   `R`—regular purchase
    -   `C`—one-click purchase
    -   `U`—autopurchase
-   `period`, string, `^[DWMQY]$`—frequency of debits \(for a regular COF purchase\), possible values:
    -   `D`—daily
    -   `W`—weekly
    -   `M`—monthly \(if the set day is not available in the next month, for example, 31, the payment is performed on the last day of the month\)
    -   `Q`—quarterly
    -   `Y`—annually
-   `amount`, integer—fixed amount of subsequent debits \(for a regular COF purchase\) in the smallest currency unit
-   `interval`, integer—multiplier to increase debiting frequency \(i.e. the interval of performing regular COF purchases\). This parameter is used in conjunction with the `period` parameter and should be assigned a numeric value from `1` to `100`
-   `time`, string, `^([0-1][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$`—time of performing subsequent debits \(for a regular COF purchase\) in the `hh:mm:ss` format. The parameter is used if the `period` parameter is specified in the request
-   `start_date`, string, `^([0-3]\\d-){2}[1-2]\\d{3}$`—date on which the first debit operation is performed \(for a COF regular purchase\). This parameter is used in conjunction with the `scheduled_payment_id` parameter and should be specified in the `DD-MM-YYYY` format
-   `expiry_day`, integer orstring—calendar day on which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `31`, without a leading zero, in accordance with the Gregorian calendar\)
-   `expiry_month`, integer orstring—month in which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `12`, without a leading zero, in accordance with the Gregorian calendar\)
-   `expiry_year`, integer—year in which the specified duration period of the COF purchase will end \(in the `YYYY` format, in accordance with the Gregorian calendar\)
-   `scheduled_payment_id`, string—identifier assigned to the payment within which scheduled debits are performed, it must differ from the identifier of the payment made to register a COF purchase that is specified in `payment_id`

 ```language-json
{
    "register": true,
    "type": "U"
}
```

 ```language-json
%7B%22register%22%3Atrue%2C%22type%22%3A%22U%22%7D%2C
```

|
|`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](en_PP_method_NewTab.md#)\).

 Can have one of the following values:

 -   `0`—the payment form should beopened usingeither the default method or a different method specified in other parameters,
-   `1`—the payment form should beopened in a new HTML page.

 If the `merchant.js` library is used \([details](en_pp_interaction_organisation.md#)\), 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.

 Can have one of the following values:

 -   `iframe`—opens the pagein 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 tab\),
-   `parent_page`—opens the pagein the currently active tab,
-   `blank_page`—opens the pagein a new tab.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 Example: `blank_page`

|
|`redirect_fail_url`  
 string, optional

|URL for final redirection to the web service if the purchase is declined.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 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](en_PP_method_NewTab.md#)\).

 Can have one of the following values:

 -   `0`—the payment form should beopened using eitherthe default method or a different method specified in other parameters,
-   `1`—the payment form should beopened in a new HTML page.

 If the `merchant.js` library is used \([details](en_pp_interaction_organisation.md#)\), 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.

 Can have one of the following values:

 -   `iframe`—opens the pagein 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 tab\),
-   `parent_page`—opens the pagein the currently active tab,
-   `blank_page`—opens the pagein a new tab.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 Example: `parent_page`

|
|`redirect_success_url`  
 string, optional

|URL for final redirection to the web service by customer decision when a purchase is completed.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 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.

 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](en_PP_redirect_modes.md#).

 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.

 Can have one of the following values:

 -   `iframe`—opens the pagein 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 tab\),
-   `parent_page`—opens the pagein the currently active tab.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

 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.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md#).

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

|
|`region_code`  
 string, optional

|The country code for the customer's address.

 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.

 Pattern: `^[A-Z]{2}$`.

 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.

 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.

 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.

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

 Pattern: `^[A-Z]{2}$`.

 Example: `IT`

|
|`sender_descriptor`   
 string, optional

|Information about the merchant provided to other parties involved in card payment processing and subsequently to customers.

 Can be used for issuing payouts. The length of the string is limited to 22 characters for cards of the Mastercard card network and 25 characters for cards of the Visa card network. For more information on working with this parameter, see [this article](en_pp_descriptor.md).

 Example: `Cosmotour* to the Moon`

|
|`sender_first_name`   
 string, optional

|The first name of the payment sender.

 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.

 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 specifiedin the same query.

 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.

 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.

 Should be generated using the appropriate algorithm after all relevant parameters have been specified \(see [this article](en_platform_signature.md#)\).

|
|`style_id`  
 integer, optional

|The identifier of the payment form design style.

 Can be used for the Payment Page design style \(see [this article](en_PP__design_customisation.md#)\).

 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 \(see [this article](en_PP_method_Embedded.md#)\).

 Example: `widget-container`

|
|`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 modeby specifying the value received in the payout registration callback \(see [this article](en_pp_payout.md)\).

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

|

**Parent topic:**[Payment Page](en_PP_about.md)