Payments quick guide

If you're implementing a Search, look and book integration use this guide to learn how to check available payment options and define how the traveller will pay when creating an order.

Payment overview

Payment handling is integrated into the required /accommodations and /orders endpoints.

Use these endpoints within your application flow to:

✅ Display payment timings and methods to travellers.

✅ Process their chosen payment method during booking.

Before diving into implementation details, ensure you're familiar with the available timings, schedules and payment methods available for each accommodation.

Step 1 - Check available payment options

Search and look

When travellers search for or view accommodations, use the following endpoints to check when and how payment can be made.

Display the appropriate payment options based on your particular payment scenario.

Filter by payment timing

Use the payment.timing filter to return only properties that support a specific payment timing:

• pay_at_the_property
• pay_online This filter is inclusive—properties supporting both timings will always be returned.

See the filters and pagination section for details.

Book and pay

Once the traveller selects a product to book, use the /orders/preview endpoint to get payment-specific details.

Handling multiple payment timings

• If the response includes more than one available payment timing (e.g. pay_online_later and pay_at_the_property), display both options to the traveller and allow them to choose.
• Only one timing should be included in the /orders/create request.

Step 2 - Review sample preview responses

You can find all payment-related details in the general_policies.payment field of the order/preview responses.

Example - Pay online now

A property that supports pay_online_now with a Virtual Credit Card (VCC) may return:

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

What this means:

• method_required:true - Payment method must be provided.
• Dates - Include a schedule of instalments.

• 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, when using pay_online_later and VCC as payment method, the /orders/preview response may include:

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

What this means:

• method_required:true - Payment method must be provided.
• Dates - Contain three payment schedule instalments, 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).

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

• cash - Cash is accepted 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

Some pay-at-property bookings include prepayment:

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

Step 3 - Create the order

After previewing payment details and confirming the traveller's choice, create the booking using the /orders/create endpoint.

• Make sure your request matches the timing and method selected in the preview.
• Follow the relevant use case for your payment flow.

Go to the payment use case that matches your scenario.

Testing your integration

We recommend testing all payment flows before going live.

Use the sandbox environment and this test accommodation:

• **ID: 10507360 - Demand API sandbox Hotel Orion. **

When testing online payments with 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.

Troubleshooting common issues

• Refer to the Payment errors section for more examples