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 handling is integrated into the required travel service API collection (/accommodations or /cars) and /orders endpoints.
Use these endpoints within your application flow to:
✅ Display payment timings, schedules and methods to travellers.
✅ Process their payment during booking.
Before diving into implementation details, ensure you're familiar with:
Use Payments if you are implementing a Search, look and book integration for:
- Accommodation (v3.1, v3.2)
Skip this section if you are implementing a Content only integration.
When travellers search for a travel service, use the following endpoints to check when and how payment can be made.
Display the appropriate payment options based on your particular payment scenario.
| Endpoint | Use it to ... |
| /search /availability | Retrieve supported payment timings available for a product. |
| /details | Retrieve accepted payment methods (payment cards and/or cash) for the selected product. |
See the Try out section to learn how to test these endpoints.
Filter by payment timing
Use the
payment.timingfilter to return only products that support a specific payment timing.
For accommodation:
pay_at_the_propertypay_onlineThis filter is inclusive—properties supporting bothpay_online_laterandpay_online_now.See the Filtering and sorting guide for details.
Use the payment.timing filter to return only products that support a specific payment timing.
For accommodation:
pay_at_the_propertypay_online- This filter includes products that support bothpay_online_laterandpay_online_now.
Example accommodation/search request:
{
"booker": {
"country": "nl",
"platform": "desktop"
},
"checkin": "2026-09-08",
"checkout": "2026-09-15",
"city": -2140479,
"filters": {"payment": {"timing": "pay_online"}},
"extras": [
"extra_charges",
"products"
],
"guests": {
"number_of_adults": 2,
"number_of_rooms": 1
}
}See the Accommodation - Filtering and sorting guide for details.
For car rentals:
pay_at_pickuppay_online_nowpay_partial_online_now
Example cars/search request:
{
"booker": {
"country": "nl"
},
"currency": "EUR",
"driver": {
"age": 36
},
"payment": {
"timings": [
"pay_online_now"
]
},
"route": {
"dropoff": {
"datetime": "2026-11-10T11:05:00",
"location": {
"city": -2140479
}
},
"pickup": {
"datetime": "2026-11-05T11:05:00",
"location": {
"city": -2140479
}
}
}
}See the Car rental - Filtering and sorting guide for details.
Example accommodation/search request:
{
"booker": {
"country": "nl",
"platform": "desktop"
},
"checkin": "2026-09-08",
"checkout": "2026-09-15",
"city": -2140479,
"filters": {"payment": {"timing": "pay_online"}},
"extras": [
"extra_charges",
"products"
],
"guests": {
"number_of_adults": 2,
"number_of_rooms": 1
}
}Once the traveller selects a product to book, use the /orders/preview endpoint to get payment-specific details.
Always use /orders/preview to dynamically determine current payment options. These may change based on property policy or availability.
| Endpoint | Use it to ... |
|---|---|
| /orders/preview | Check the final details of the selected accommodation and products, including:
|
If a traveller is booking multiple products, /orders/preview returns only information that is valid for every item in the order.
Handling multiple payment timings
- If the response includes more than one available payment timing (e.g.
pay_online_laterandpay_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.
You can find all payment-related details in the general_policies.payment field of the order/preview responses.
- If
method_requiredistruein preview response, you must include a supported payment method in the /orders/create request (e.g. VCC or credit card, depending on the flow). - If false, the booking does not require a method upfront—common for fully flexible rates and pay at the property timings.
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": "2026-11-18",
"price": {
"accommodation_currency": 200.64,
"booker_currency": 200.64
}
},
{
"at": "2026-12-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.
Schedule | Date (at) | Amount (price) |
|---|---|---|
| Booking date | 2026-11-18 | 200.64 – main booking charge without extra charges (if any). |
| Check-in date | 2025-01-10 | 5.14 – additional charges collected on-site. |
- 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,3and4).- You must be able to generate/obtain a VCC for one of these cards.
See Pay online using VCC use case for implementation examples.
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": "2026-11-18",
"price": {
"accommodation_currency": 0.00,
"booker_currency": 0.00
}
},
{
"at": "2026-12-01",
"price": {
"accommodation_currency": 200.64,
"booker_currency": 200.64
}
},
{
"at": "2026-12-03",
"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.
Schedule | Date (at) | Amount (price) |
|---|---|---|
| Booking date | 2026-11-18. | 0.00 – no prepayment required |
| Payment date | 2026-12-01 - This date will be either when free cancellation period has expired, or 48 hours before the checkin date. | The amount to be charged to the provided payment method. In this case 200.64. |
| Check-in date | 2026-12-03 | 5.14 – extra charges due at check-in. |
- 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,3and4).
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": "2026-11-01",
"price": {
"accommodation_currency": 0,
"booker_currency": null
}
},
{
"at": "2026-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:
Schedule | Date (at) | Amount (price) |
|---|---|---|
| Booking date | 2026-11-18 | 0.00 – no prepayment is required before the checkin date. |
| Check-in date | 2026-11-18 | 177.65 – full payment at check-in. |
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).
Some pay-at-property bookings include prepayment:
{
"general_policies": {
"payment": {
"pay_at_the_property": {
"method_required": true,
"dates": [
{
"at": "2026-11-01",
"price": {
"accommodation_currency": 0.00,
"booker_currency": 0.00
}
},
{
"at": "2026-11-18",
"price": {
"accommodation_currency": 439.85,
"booker_currency": 57.27
}
},
{
"at": "2026-11-18",
"price": {
"accommodation_currency": 585.88,
"booker_currency": 76.29
}
}
]
}
}
}
}
- Use the common/payments/cards endpoint to match card IDs to card types.
- See the schedules for more information.
You can find all payment-related details in the policies.payment field of the order/preview responses.
{
"request_id": "01fr9ez700exycb98w90w5r9sh",
"data": {
"car": {
"offer": 123456789,
"currency": { … },
"price": { … },
"policies": {
"cancellation": { … },
"damage_excess": { … },
"deposit": { … },
"fuel_policy": "return_same",
"mileage": { … },
"payment": {
"dates": [
{
"at": "2025-11-01",
"amount": {
"display": {
"value": 129.99,
"currency": "EUR",
"timing": "pay_online_now"
},
"pay": {
"value": 129.99,
"currency": "EUR",
"timing": "pay_online_now"
}
}
}
]
},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.
You can charge travellers
You cannot charge travellers directly
You are a Corporate partner
Your traveller pays at property
We recommend testing all payment flows before going live.
Use the sandbox environment and any of the provided test properties.
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.
| Issue | Cause | Recommendation |
|---|---|---|
| 400 – missing payment method | method_required is true, but no method provided. | Use a supported VCC or card in /orders/create |
| Unexpected timing | Preview returns multiple payment options. | Choose one and match it in your order. |
| Card ID mismatch | Provided card ID not supported. | Use IDs returned in the preview response. |
- Refer to the Payment errors section for more examples
- For more tips and examples on how to preview and create an order, check the Orders section
- Learn about all the available payment methods and timings.
- You can also explore the different payment models for instructions, examples and best practices for payments.