Using addendum with itinerary data

Payment Page allows you to include so-called financial detail addendum in your payment request you submit to the payment platform. The addendum data is widely used in travel industry and contains detailed booking and itinerary information such as booking number, hotel guest name(s) and check-in and check-out dates. The addendum data are submitted into the payment platform along with the payment request details. Usage of addendum data allows payment providers to make payments more secure and offer more competitive rates.

Payments with addendum data follow the general processing routine except for some specific requirements:

  • Not all MCCs are applicable Addendum data is used only in travel industry; that is why only merchants with the following MCC codes can initiate payments with hotel booking data: 3501–3999 and 7011.
  • Addendum data must always be included in the initial checkout request Any checkout that involves transmission of addendum data must start with a request that contains addendum data. Though, you may omit addendum data in any other requests you send to you payment provider. If you fail to send addendum data in the initial request, and then attempt to use addendum data in any of the subsequent messages, payment platform will refuse to process your request and will return an error message.

Addendum data may be used only in operations that use Visa and Mastercard cards.

All the booking itinerary information is packed into a single value, included in the addendum_data parameter which in its turn is added in checkout request as an optional parameter, along all the other checkout parameters. The following section describes how to calculate the addendum_data parameter value on the basis of all the booking itinerary data.

How to obtain the addendum_data parameter value?

The addendum_data parameter can contain only one value, which must incorporate all the booking itinerary information. The following instructions describe how to calculate the addendum_data parameter value based on booking itinerary information.

  1. Convert all the booking itinerary data in the lodging JSON object. For more information about the child objects of lodging, see Addendum parameters in the Gate API.

    Here is and example of the lodging object with hotel booking itinerary:

    Figure: Example of a JSON object with hotel booking details

    {
 "lodging": {
  "customer_service_toll_free_number": "88005553535", // 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
  }
 }
}

  2. Encode the lodging JSON object with the itinerary data by using the Base64 encoding algorithm.

    Here is Base64-encoded representation of the JSON object from step1 (before encoding, all comments were deleted):
    ewogImxvZGdpbmciOiB7CiAgImN1c3RvbWVyX3NlcnZpY2VfdG9sbF9mcmVlX251bWJlciI6ICI4ODAwNTU1Mz
UzNSIsCiAgImd1ZXN0X25hbWUiOiAiSm9obiBTbWl0aCIsCiAgImNoZWNrX2luX2RhdGUiOiAiMTAtMTItMjAx
OSIsCiAgImNoZWNrX291dF9kYXRlIjogIjIyLTEyLTIwMTkiLAogICJmb2xpb19udW1iZXIiOiAiNTYyNjU2NT
VBQkMiLAogICJmaXJlX3NhZmV0eV9hY3RfaW5kaWNhdG9yIjogdHJ1ZSwKICAicm9vbSI6IHsKICAicmF0ZSI6
IDEyLAogICJudW1iZXJfb2ZfbmlnaHRzIjogIjEyIgogIH0sCiAgImNoYXJnZXMiOiB7CiAgInRyYW5zcG9ydG
F0aW9uIjogMTIwMCwKICAiaW50ZXJuZXRfYWNjZXNzIjogNDUwMAogIH0KIH0KfQ==

Actually, this is the value you need to set the addendum_data parameter to.

You are required to include the addendum_data parameter in checkout request parameters, required and optional ones, well before signing the request. Here is example of opening the Payment Page payment form for checkout with addendum data (for simplicity some values are abbreviated):
EPayWidget.run(
    { payment_id: 'X01254',     // Payment ID
      payment_amount: 20000,    // Amount
      payment_currency: 'USD',  // Currency
      project_id: 258,          // Merchant ID
      customer_id: '123',       // Customer ID
      addendum_data: "ewogImxvZGdpbmciOiB7CiAgImN1c3Rv...==" // Addendum data
      signature: "kUi2x9dKHAVNU0FYlSCQ9vySO\/RLCvhtT...=="   // Signature
    }
)

Related links