# Specifying extended purchase data for subsequent merchant use {#en_pp_additional_data}

An article about the capability of capturing relevant purchase information via Payment Page for internal merchant use.

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)

## Introduction {#en_pp_additional_data_overview}

In addition to specifying required and provider-recommended parameters inpayment requests, merchants sometimes need to pass data that is related to specific payments and their statuses andthat can be subsequently used by merchantsat their discretion. For this purpose, the Payment Page API includes the parameters that allow passing various data in requests and receiving these data together with other information in final callbacks.

**Note:** When processing payments via Gate, you can use [similar capabilities](en_gate_additional_data.md#).

## Specifying booking data {#en_pp_booking_data}

### Overview {#section_eqc_4gh_h1c .section}

The `booking_info` parameter allows you to keep track of booking information relevant to a certain payment and receive this information in callbacks from the payment platform. This capability can be applied in a wide range of use cases \(for example, to specify information about booking concert tickets\) and with sufficient flexibility as there are no restrictions by MCC \([Merchant Category Code, MCC](en_glossary.md#)\). If you have questions concerning the use of this capability, refer to your Ecommpay account manager for more details.

The `booking_info` parameter can be used for processing almost all types of paymentsmade with cards, Apple Pay,Click to Pay, and Google Pay: it includes performing such actions as purchase processing, placing authorisation holds, registering unscheduled COF purchases, and payment instrument verification.

**Warning:** In order to enhance the quality of payment processing and ensure compliance with industry standards, starting from January 15, 2026, merchants in certain business categories must specify the `booking_info` parameter containing information about the start and end dates of the booked service \(in the`start_date` and `end_date` parameters\), for each initiated [card purchase](en_pm_cardpayments.md). This requirement applies to merchants with Merchant Category Codes \(MCC\) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519, and 7922.

### Use case {#section_qkq_ryl_h1c .section}

Here is an example of a use case when a merchant in the music festival industry needs to:

-   collect and process data about music festival tickets booked by the customers.
-   Provide the company's employees with the timely access to such information about each customer.

For this purpose, the following workflow is set up:

1.  Each request for opening Payment Page sent from the web service contains booking information in the `booking_info` parameter. The value of this parameter is a string containing a Base64 encoded JSON object.

    The JSON object can include the following data.

    -   The `bookers` array with the information about the customers for whom the service is booked. Each element of this array contains:
        -   `first_name`—the name of the customer provided at the time of booking
        -   `last_name`—the last name of the customer provided at the time of booking
        -   `email`—the email provided at the time of booking
    -   The `items` array with the information about separate services included in the booking. Each element of this array contains:
        -   `description`—description of the service included in the booking
        -   `start_date`—starting date of the service included in the booking
        -   `end_date`—ending date of the service included in the booking
    -   Parameters with other details of the booking:

        -   `start_date`—starting date of the booked service
        -   `end_date`—ending date of the booked service
        -   `description`—a free-form description of the booked service
        -   `total`—the total cost of the booking
        -   `pax`—the number of people per booking
        -   `reference`—the booking reference, which can be the URL, the name of the booked service, or its code in the merchant web service
        -   `id`—the identifier of the booking, unique in the merchant web service
        **Note:** Keep in mind that the standalone parameters `start_date` and `end_date` included in the JSON object are intended for specifying the starting and ending dates of the booking as a whole, while parameters `start_date` and `end_date` of the `items` array are intended for specifying the starting and ending dates of the separate services included in the booking.

        **Warning:** The value of parameters `total` and `pax` must be greater than `0`.

2.  When a relevant operation has been processed, the information specified in the `booking_info` parameter is passed to the merchant web service in the final callbackand can be viewed in the payment information tab in Dashboard.
3.  The web service processes this information as needed together with the rest of the operation data.

### Setup {#section_j4j_r2n_h1c .section}

The capability of using the `booking_info` parameter in requests and receiving booking information in callbacks \(with standard format\) is available by default and does not require any specific setup.

### Data format {#section_wcl_w2n_h1c .section}

The `booking_info` parameter can be specified in requests for opening Payment Page as a string containing the Base64 encoded JSON object \(`booking_info`\) with the necessary booking parameters.

|Parameter|Description| |
|---------|-----------|--|
|`bookers`  
 array

|Array with the information about the customers for whom the service is booked|1|
|`first_name`  
 string

|Name of the customer provided at the time of booking|1-11|
|`last_name`  
 string

|Last name of the customer provided at the time of booking|1-21|
|`email`  
 string

|Email provided at the time of booking|1-31|
|`items`  
 array

|Array with the information about separate services included in the booking|2|
|`description`  
 string

|Description of the service included in the booking|2-12|
|`start_date`  
 string

|Starting date of the service included in the booking, in the `DD-MM-YYYY` format|2-22|
|`end_date`  
 string

|Ending date of the service included in the booking, in the `DD-MM-YYYY` format|2-32|
|`start_date`  
 string

|Starting date of the booked service, in the `DD-MM-YYYY` format|3|
|`end_date`  
 string

|Ending date of the booked service, in the `DD-MM-YYYY` format|4|
|`description`  
 string

|Free-form description of the booked service|5|
|`total`  
 integer

|Total cost of the booking. Must be greater than `0`|6|
|`pax`  
 integer

|Number of people per booking. Must be greater than `0`|7|
|`reference`  
 string

|Booking reference, which can be the URL, the name of the booked service, or its code in the merchant web service|8|
|`id`  
 string

|Identifier of the booking, unique in the merchant web service|9|

```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"
}
```

```
ewogICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAiZGVzY3JpcHRpb24iOiAiU2lkZXJpcyBtdXNpYyBmZXN0aXZhbCBmdWxsIHBhc3MiLAogICJ0b3RhbCI6IDIwMDAwMCwKICAicGF4IjogMiwKICAiYm9va2VycyI6IFsKICAgICB7CiAgICAgICAgImZpcnN0X25hbWUiOiAiV2lsbGlhbSIsCiAgICAgICAgImxhc3RfbmFtZSI6ICJIZXJzY2hlbCIsCiAgICAgICAgImVtYWlsIjogInJzZmVsbG93QG1haWwuY29tIgogICAgIH0sCiAgICAgewogICAgICAgICJmaXJzdF9uYW1lIjogIkNhcm9saW5lIiwKICAgICAgICAibGFzdF9uYW1lIjogIkhlcnNjaGVsIiwKICAgICAgICAiZW1haWwiOiAic2FsYXJpZWRhc3Ryb25vbWVyQG1haWwuY29tIgogICAgIH0KICBdLCAgICAgICAgCiAgIml0ZW1zIjpbCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgQXJyaXZhbCIsCiAgICAgICAgInN0YXJ0X2RhdGUiOiAiMTItMDgtMjAyNiIsCiAgICAgICAgImVuZF9kYXRlIjogIjEyLTA4LTIwMjYiCiAgICAgfSwKICAgICB7CiAgICAgICAgImRlc2NyaXB0aW9uIjogIkhvdGVsIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxMi0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9LAogICAgIHsKICAgICAgICAiZGVzY3JpcHRpb24iOiAiQ29uY2VydHMiLAogICAgICAgICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICAgICAgICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IgogICAgIH0sCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgRGVwYXJ0dXJlIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9CiAgXSwKICAicmVmZXJlbmNlIjogIm11c2ljZmVzdGxpbmsiLAogICJpZCI6ICI4MyIKfQ==
```

```language-json
{
    "payment": {
        "date": "2024-01-24T06:24:45+0000",
        "method": "card",
        "id": "FESTIVAL_PASS_1781",
        "sum": {
            "amount": 0,
            "currency": "EUR"
        },
        "type": "purchase",
        "status": "refunded",
        "description": "FESTIVAL_PASS_1781"
    },
    "project_id": 111738,
    "customer": {
        "id": "musicaficionado_83"
    },
    "account": {
        "number": "551115******1822",
        "token": "7123ba1f24f16a115f3390a9",
        "type": "mastercard",
        "card_holder": "WILLIAM HERSCHEL",
        "expiry_month": "08",
        "expiry_year": "2030"
    },
    "booking info": \{    // Object with the booking information
        "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"
    \},
    "operation": {
        "provider": {
            "payment_id": "0010000124258736",
            "auth_code": "",
            "endpoint_id": 414,
            "id": 414
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "EUR"
        },
        "code": "0",
        "message": "Success",
        "id": 55386010114429,
        "type": "refund",
        "status": "success",
        "date": "2024-01-24T06:24:45+0000",
        "sum_initial": {
            "amount": 200000,
            "currency": "EUR"
        },
        "created_date": "2024-01-24T06:24:43+0000",
        "request_id": "abcaf52323381a-d988c158cc4b43046-00055387"
    }
}
```

## Specifying other extended purchase data {#en_pp_merchant_data}

### Overview {#section_thq_xq3_pzb .section}

The `merchant_data` parameter can be used for keeping track of extended information about the order, applying promotions and bonus points, and other relevant data.In addition, the value of this parameter can be combined with the information passed in the `payment_description` parameter and the receipt information passed in the `receipt_data` object. As a result, all necessary data can be provided in callbacks without passing certain pieces of information multiple times in different parameters.

### Use case {#section_fln_zq3_pzb .section}

Here is an example of a use case when a merchant in the video game industry needs to:

-   collect and process data about add-on services that the gamers purchase as they play.
-   Provide the company's employees with the timely access to such information about each customer.

Merchant specialists in charge of the integration inform the Ecommpay account manager about these requirements.As a result, the following workflow is devised and set up:

1.  Each request for opening Payment Page sent from the merchant web service contains information about the purchased services—passed as a JSON object in the `merchant_data` parameter.

    The `merchant_data` string includes the following:

    -   The `items` array in which each element contains the SKU \(`sku`\), the description \(`description`\), and the number of the purchased services \(`count`\).
    -   The `total_count` parameter with the total number of the purchased services or goods items.
    -   The `user_id` parameter with the internal identifier of the customer.
2.  When a payment has been processed, the information specified in the `merchant_data` string is passed to the merchant web service in the final callback and can be viewed in the payment information tab in Dashboard.
3.  The web service processes this information as needed together with the rest of the payment data.

![](images/ecommpay/en_pp_additional_data.svg "Placing an order in the web service")

![](images/ecommpay/en_merchant_data_db.svg "Viewing information in Dashboard")

### Setup {#section_yfz_yq3_pzb .section}

To use the capability of passing information in the `merchant_data` parameter, contact your account manager. The capability is set up in the payment platform by the Ecommpay specialists who will subsequently inform you that it is ready to be usedand that the extended information is now available in callbacks and in the Dashboard interface.

### Data format {#section_lg1_cr3_pzb .section}

In requests for opening Payment Page to process payments, the data specified in the `merchant_data` parameter must be passed as a JSON object. However, because this parameter is a string \(string\), to pass the JSON object in it when using the HTTP POST method, you need to escape the `"` character \(quotation mark,U+0022\) by adding `\` \(backlash or reverse solidus,U+005C\) in front of it.It is necessary in order to distinguish on the level of programmatic interaction which quotation marks close the string and which quotations marks are part of the JSON contents within the string. At the same time, when sending HTTP GET requests, there is no need to use escape sequences if you pass a JSON object \(the string is going to be interpreted correctly in this case even without escaping\).

In final callbacks with payment results, the data specified in the `merchant_data` parameter is passed in the `data` parameter of the `merchant` object.

In the following examples, the contents of the parameter are split into several lines for the reader's convenience.

```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"}"
```

```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\"}"
```

```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\"}" 
}
```