How to use Payments

If you are implementating a Search, look and book integration, use this quick guide to learn how to check the available payment options, so you can later define your order request for your bookings.

Payment endpoints

Payments functionality is built into the required /accommodations and /orders endpoints.

You can use the following endpoints in your application flow to provide travellers with the necessary information on when and how they can pay, and to process their chosen payment option.

Before going to specific instructions on different payment scenarios you must check the available timings, schedules and payment methods, for the desired accommodations.

Check the available payment options

Search and look

When a traveller is searching for or looking at somewhere to stay, use the following endpoints to provide them with the information on when and how they can pay. You should present the appropriate payment options in line to your particular payment scenario.

Book and pay

When the traveller has selected the product they want to book:

You can see all payment-related details in the general_policies.payment field provided in the response. That is:

• What payment timings the business traveller can use.
• And for each payment timing,
  • What method they can use to secure the booking.
  • And the available schedule: date(s) on which payment(s) must be made.

See some examples of orders/preview responses for both Online payments and Pay at property options.

Example pay_online_now

In this example, for the selected property and product, a partner that is entitled to pay_online_now using a VCC, would find these options in the /orders/preview response:

"accommodation": {
           ...
           "general_policies": {
               "payment": {
                   ...
                   "pay_online_now": {
                       "method_required": true,
                       "dates": [
                           {
                               "at": "2023-12-18",
                               "price": {
                                   "accommodation_currency": 200.64,
                                   "booker_currency": 200.64
                               }
                           },
                           {
                               "at": "2024-01-10",
                               "price": {
                                   "accommodation_currency": 5.14,
                                   "booker_currency": 5.14
                               }
                           }
                       ],
                       "methods": {
                           ...
                           "cards": [1,2,3,4,...]

• The method_required is set to true

• Dates: Contain two payment schedule items, showing how and when the total price of the booking must be paid:

  Schedule	at	price
  First item	The booking date (In this example 2023-12-18).	In pay_online_now timing, the total amount that must be charged for the stay without extra charges (if any). In this case 200.64
  Second item	The checkin date for the booking.	The extra charges amount that will be collected at the property at checkin date. In this case 5.14.

• The methods.cards: Contains the IDs of accepted payment cards that can be used to pay for or secure a booking (in this case, 1,2,3 and 4).

• You must be able to generate/obtain a VCC for one of these cards.

Example pay_online_later

In this example, for the selected property and product, a partner that is entitled to pay_online_later using a VCC, would find these options in the /orders/preview response:

  "accommodation": {

           ...
           "general_policies": {
               "payment": {
                   ...
                   "pay_online_later": {
                       "method_required": true,
                       "dates": [
                           {
                               "at": "2023-12-18",
                               "price": {
                                   "accommodation_currency": 0.00,
                                   "booker_currency": 0.00
                               }
                           },
                           {
                               "at": "2024-01-09",
                               "price": {
                                   "accommodation_currency": 200.64,
                                   "booker_currency": 200.64
                               }
                           },
                           {
                               "at": "2024-01-10",
                               "price": {
                                   "accommodation_currency": 5.14,
                                   "booker_currency": 5.14
                               }
                           }
                       ],
                       "methods": {
                           ...
                           "cards": [1,2,3,4,...]


                       }

• The method_required is set to true

• Dates: Contain three payment schedule items, showing how and when the total price of the booking must be paid:

  Schedule	at	price
  First item	The booking date (In this example 2023-12-18).	Will always be 0 for this payment timing.
  Second item	The date on which payment will be taken. This will be either the expiry of any free cancellation period, or 48 hours before the checkin date. In this example 2024-01-09.	The amount to be charged to your provided VCC. In this case 200.64.
  Third item	The checkin date for the booking.	The extra charges amount that will be collected at the property at checkin date. In this case 5.14.

• The methods.cards: Contains the IDs of accepted payment cards that can be used to pay for or secure a booking (in this case, 1,2,3 and 4).

• You must be able to generate/obtain a VCC for one of these cards.

Example pay_at_the_property

In this example, for the selected property and product, for a pay_at_the_property payment timing, you would find this info in the /orders/preview response:

"payment": {
    "methods": {
      "cash": true,
      "cards": [
        1,
        2,
        3
      ]
    },
    "timings": [
      "pay_at_the_property"
    ]
  },

In this example:

• The available timing is: pay_at_property
• The available method is: cash but it also offers a list of accepted Id cards (1,2and3) that the traveller must use to secure their booking (as the payment will be made at checkin date).

Use filters

If you are only interested in properties that accept a specific timing then you can filter results up. Use the payment.timing filter in your requests:

• So you can restrict results to only include properties that support Pay at the property (pay_at_the_property) or Online payments (pay_online).
• The filter is not exclusive - properties that support both timings are returned whichever setting you use.

Create your order

When your traveller has selected how and when they want to book, you must use /orders/create to make the payment. You must construct the request to match the requirements of your particular use case.

• Each use case covers specific instructions on how to create the order request needed for payments.

• Go to the use case that is relevant for your payment scenario: