Specifying extended purchase data for subsequent merchant use

Introduction

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

Notice: When processing payments via Payment Page, you can use similar capabilities.

Specifying booking data

Overview

The booking_info object allows you to keep track of booking information relevant to a certain payment and receive this information in callbacks from the payment platform. In comparison to specifying the addendum with itinerary data (details) utilised in certain branches of travel industry, this capability can be applied in a wider range of use cases (for example, to specify information about booking concert tickets) and with more flexibility as there are no restrictions by MCC (Merchant Category Code, MCC) and no required parameters. At the same time, using the booking_info object may not offer the advantages that are available for addendum data capabilities, so if you have more questions concerning the use of these capabilities, refer to your ecommpay account manager for more details.

The booking_info object can be used for almost all types of payments made with cards, Apple Pay, and Google Pay, including one-time purchases (one- and two-step), unscheduled COF purchases (one-click and autopurchases), and payment instrument verification.

The booking_info object can be used for keeping track of booking information in requests. This capability is available for processing card, Apple Pay, and Google Pay payments.

Use case

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 to Gate for which specifying booking information is available contains such information—passed in the booking_info object.

    The object can include the following parameters:

    • firstname—the name of the customer provided at the time of booking
    • surname—the last name of the customer provided at the time of booking
    • email—the email provided at the time of 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
  2. When a relevant operation has been processed, the information specified in the booking_info object is passed to the merchant web service in the final callback.
  3. The web service processes this information as needed together with the rest of the operation data.

Setup

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

The capability of using the booking_info object is available by default and does not require any specific setup.

Data format

The booking_info object can be specified in requests to different endpoints and callbacks with operation results. Its structure is provided in the BookingInfo schema and its location in the request structure can be found in a particular endpoint specification.

Figure 1. Card payments
Figure 2. Apple Pay payments
Figure 3. Google Pay payments

In final callbacks with the operation result information, the data that was specified in the booking_info object of the request is passed in the booking info object.

Figure 4. Example of data passed in the payment request
"booking_info": {
    "firstname": "William",
    "surname": "Herschel",
    "email": "rsfellow@mail.com",
    "start_date": "12-08-2026",
    "end_date": "13-08-2026",
    "description": "Sideris music festival full pass",
    "total": 200000,
    "pax": 4,
    "reference": "musicfestlink",
    "id": "83"
}
Figure 5. Example of data passed in the final callback with the payment result information
{
    "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
        "firstname": "William",
        "surname": "Herschel",
        "email": "rsfellow@mail.com",
        "start_date": "12-08-2026",
        "end_date": "13-08-2026",
        "description": "Sideris music festival full pass",
        "total": 200000,
        "pax": 4,
        "reference": "musicfestlink",
        "id": "83"
    },
    "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

Overview

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

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 sent from the merchant web service to Gate contains information about the purchased services—passed as a JSON object in the data parameter of the merchant object.

    The 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 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.
Figure 6. Viewing information in Dashboard

Setup

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

Data format

In requests to process payments via Gate, 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.

In final callbacks with payment results, the data that was 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.

Figure 7. Example of data passed in the POST request (with escape sequences)
"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 8. Example of data passed in the final callback with the payment result information (with escape sequences)
"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\"}" 
}