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, use the /orders/preview endpoint.

Examples of orders/preview responses

You can find all payment-related details in the general_policies.payment field of the order/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:

• 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:

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

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.