Parameters for opening the 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 Orchid 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

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 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) 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

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

checkout_script
integer, optional

Indicator that specifies whether an encryption script is used to encrypt payment card information or not. (details):

Should be specified when making payments using a payment card or verifying its validity without specifying a card security code (CVV/CVC/CID; details). Can have one of the following values:

  • 0—do not use the encryption script,
  • 1—use the encryption script.

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

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 3. 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 4. Example resulting string
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAiYWRkcmVzc19tYXRjaCI6IlkiLAogICAgImhvbWVfcGhvbmUiOiI0NDIwNTU1MjY2MDgiLAogICAgIndvcmtfcGhvbmUiOiI0NDIwNTU1Mzc3MDkiLAogICAgImFjY291bnQiOnsgCiAgICAgICJhZGRpdGlvbmFsIjoiZ2FtZXIxMjM0NSIsCiAgICAgICJhZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAiZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAiY2hhbmdlX2luZGljYXRvciI6IjAxIiwKICAgICAgImNoYW5nZV9kYXRlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJwYXNzX2NoYW5nZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJwYXNzX2NoYW5nZV9kYXRlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJwdXJjaGFzZV9udW1iZXIiOjEyLAogICAgICAicHJvdmlzaW9uX2F0dGVtcHRzIjoxNiwKICAgICAgImFjdGl2aXR5X2RheSI6MjIsCiAgICAgICJhY3Rpdml0eV95ZWFyIjoyMjIyLAogICAgICAicGF5bWVudF9hZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAicGF5bWVudF9hZ2UiOiIwMS0xMC0yMDIyIiwKICAgICAgInN1c3BpY2lvdXNfYWN0aXZpdHkiOiIwMSIsCiAgICAgICJhdXRoX21ldGhvZCI6IjAxIiwKICAgICAgImF1dGhfdGltZSI6IjAxLTEwLTIwMjIxMzoxMiIsCiAgICAgICJhdXRoX2RhdGEiOiJsb2dpbl8wMTAyIgogICAgfQogIH0KfQ=====

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 5. Example JSON object
{ 
  "customer":{ 
    "mpi_result":{ 
      "acs_operation_id":"00000000-0005-5a5a-8000-016d3ea31d54",
      "authentication_flow":"01",
      "authentication_timestamp":"202210111050"
    }
  }
}
Figure 6. 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_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 7. 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 8. 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

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, 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 Orchid.

Example: {"id":7}

language_code
string, optional

The code of the language in which the payment form should be displayed (see this article) and the notifications should be generated (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 Orchid 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 9. 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 10. 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),
  • 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 is 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),
  • 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.

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 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 11. 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 12. Example resulting string
eyAKICAicGF5bWVudCI6eyAKICAgICJyZW9yZGVyIjoiMDEiLAogICAgInByZW9yZGVyX3B1cmNoYXNlIjoiMDEiLAogICAgInByZW9yZGVyX2RhdGUiOiIxMS0xMC0yMDIyIiwKICAgICJjaGFsbGVuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgImNoYWxsZW5nZV93aW5kb3ciOiIwMSIsCiAgICAiZ2lmdF9jYXJkIjp7IAogICAgICAiYW1vdW50IjoxMjM0NSwKICAgICAgImN1cnJlbmN5IjoiVVNEIiwKICAgICAgImNvdW50IjoxCiAgICB9CiAgfQp9==

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 Orchid 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 13. 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 14. Example resulting string
receipt_data: "eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAg
ICAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMCwKICAgICAgICAgICAgInRheCI
6MTgsCiAgICAgICAgICAgICJ0YXhfYW1vdW50IjoxODAwLAogICAgICAgICAgICAiZGVzY3JpcHRpb24iOiJEZXN
pZ24gZnJhbWUiCiAgICAgICAgIH0KICAgICAgXSwKICAgICAgInRvdGFsX3RheF9hbW91bnQiOjE4MDAsCiAgICA
gICJjb21tb25fdGF4IjoxOCAgICAgICAKfQ"

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_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

recurring
string, optional

Information about the COF purchase being registered (details).

If the Orchid 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 15. Example JSON object
{
    "register": true,
    "type": "U"
}
Figure 16. 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

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

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 (see this article).

Example: 54