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). 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 Openpayze account manager for more details.

The booking_info object can be used for almost all types of payments, including one-time purchases, unscheduled COF purchases, and payment instrument verification.

The booking_info object can be used for keeping track of booking information in requests.

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

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 2. Example of data passed in the payment request
Figure 3. Example of data passed in the payment result callback
{
    "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 extended purchase data for subsequent merchant use

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