Payments quick guide

If you are implementing 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 requests.

Payment endpoints

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

Use these endpoints within your application flow to provide travellers with details on when and how they can pay, and to process their chosen payment option.

Before exploring specific instructions for different payment scenarios, ensure you check the available timings, schedules and payment methods, for the desired accommodations.

Checking available payment options

Search and look

When a traveller is searching for or looking at accommodations, use the following endpoints to provide information on when and how they can pay. Display the appropriate payment options based on your particular payment scenario.

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.

Check the filters and pagination section for more details.

Book and pay

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

You can find all payment-related details in the general_policies.payment field of the response, including:

• The payment timings available to the traveller.
• And for each payment timing,
  • The methods available to secure the booking.
  • And the payment schedule: date(s) on which payment(s) are due.

Examples of orders/preview responses

Pay online now

In this example, for the selected property and product, when using pay_online_now and a Virtual credit card (VCC) as payment method, the /orders/preview response would retrieve:

"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, indicating how and when 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 are 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.

Pay online later

In this example, for the selected property and product, when using pay_online_later and VCC as payment method, the /orders/preview response would be similar to:

"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-11",
                           "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 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 when free cancellation period has expired, or 48 hours before the checkin date. In this example 2024-01-09.	The amount to be charged to the provided payment method. 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).

Pay at the property (without prepayment)

In this example, for the selected property and product, for a pay_at_the_property payment timing without a prepayment policy, the /orders/preview response would return something similar to:

          "pay_at_the_property": {
        "dates": [
          {
            "at": "2024-11-01",
            "price": {
              "accommodation_currency": 0,
              "booker_currency": null
            }
          },
          {
            "at": "2024-11-18",
            "price": {
              "accommodation_currency": 177.65,
              "booker_currency": null
            }
          }
        ],
        "method_required": true,
        "methods": {
          "cash": true,
          "cards": [
            1,
            2
          ],

        }
  

• Dates: Contain two payment schedule items, showing wwhen the instalment is scheduled and the amount:

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

Pay at the property with prepayment

Pay at the property timing can also include a prepayment policy that schedules different instalments at different dates. Example:

"general_policies": {
           "payment": {
               "pay_at_the_property": {
                   "method_required": true,
                   "dates": [
                       {
                           "at": "2024-11-01",
                           "price": {
                               "accommodation_currency": 0.00,
                               "booker_currency": 0.00
                           }
                       },
                       {
                           "at": "2024-11-10",
                           "price": {
                               "accommodation_currency": 439.85,
                               "booker_currency": 57.27
                           }
                       },
                       {
                           "at": "2024-11-18",
                           "price": {
                               "accommodation_currency": 585.88,
                               "booker_currency": 76.29
                           }
                       }
                   ],

Creating an order

Once a traveller has chosen how and when to book, use /orders/create to process the payment.

Construct your request to match the specific requirements of your payment scenario.

• Each use case includes detailed instructions on how to create the order request.

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

Testing

We recommend testing different payment options before going live. Use our sandbox environment and the test accommodation ID: 10507360 - Demand API sandbox Hotel Orion.

When simulating payments with credit cards:

• Use a real credit card with enough funds to avoid errors.
• Include real credit card details in your request.
• Payment will be charged to the provided card.

Booking.com automatically refunds the payment the following Monday after testing.