Specifying extended purchase data for subsequent merchant use

Overview

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. 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 parameter 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 parameter can be used for processing almost all types of payments: it includes performing such actions as purchase processing, placing authorisation holds, registering unscheduled COF purchases, and payment instrument verification.

The booking_info parameter 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. 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
     Notice: 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 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 operation data.

Setup

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.

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

Data format

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.

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

Setup

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