# Accommodation payments quick guide **If you're implementing a [Search, look and book integration](/demand/docs/development-guide/application-flows/#search-look-book) 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 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. ![How to use payments](/assets/overview_how-to-use-payments.9ed2c436d1bf5d700e2736fb42facfd10ad1cb9fc002df04827a802171af5532.fe580a34.jpg) Before diving into implementation details, ensure you're familiar with: * [Payment timings](/demand/docs/payments/payments-timings/) * [Payment schedules](/demand/docs/payments/payments-schedules) * [Payment methods](/demand/docs/payments/payments-methods/) ## Do I need Payments? Use Payments if you are implementing a [Search, look and book](/demand/docs/development-guide/application-flows#search-look-and-book) integration for: * Accommodation (v3.1, v3.2) Skip this section if you are implementing a [Content only](/demand/docs/development-guide/application-flows#content-only) integration. ## Step 1 - Check available payment options ### Search and look 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](/demand/docs/payments/payments-timings/) available for a product. | | /details | Retrieve accepted [payment methods](/demand/docs/payments/payments-methods/) (payment cards and/or cash) for the selected product. | See the [Try out section](/demand/docs/getting-started/try-out-the-api/#steps) to learn how to test these endpoints. ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) **Filter by payment timing** > Use the `payment.timing` filter to return only products that support a specific payment timing. > For accommodation: * `pay_at_the_property` * `pay_online` This filter is inclusive—properties supporting both `pay_online_later` and `pay_online_now`. See the [Filtering and sorting guide](/demand/docs/accommodations/filter-sorting) for details. #### Filter by payment timing Use the `payment.timing` filter to return only products that support a specific payment timing. **For accommodation:** * `pay_at_the_property` * `pay_online`- This filter includes products that support both `pay_online_later` and `pay_online_now`. Example accommodation/search request: ```json { "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](/demand/docs/accommodations/filter-sorting) for details. **For car rentals:** * `pay_at_pickup` * `pay_online_now` * `pay_partial_online_now` Example cars/search request: ```json { "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](/demand/docs/cars/cars-filter-sorting) for details. **Example accommodation/search request:** ```json { "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 } } ``` ### Book and pay Once the traveller selects a product to book, use the [/orders/preview endpoint](/demand/docs/open-api/demand-api/orders/orders/preview) 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](/demand/docs/open-api/demand-api/orders/orders/preview) | Check the final details of the selected accommodation and products, including:* When ([payment timings](/demand/docs/payments/payments-timings/)) the traveller is expected to pay. * Which [payment methods](/demand/docs/payments/payments-methods/) are accepted to secure the reservation. * For pay online now / later, securing the reservation also means completing the payment. * For pay at the property, the payment methods provided in [/orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) might only be used for cancellation and no show fees. --- | Multiple products If a traveller is booking multiple products, [/orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) returns only information that is valid for every item in the order. ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) **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. * If `method_required` is `true` in 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. ### Example - Pay online now A property that supports `pay_online_now` with a Virtual Credit Card (VCC) may return: ```json { "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`,`3` and `4`). * You must be able to generate/obtain a VCC for one of these cards. See [Pay online using VCC use case](/demand/docs/payments/models/partner-collects#2-create-your-order-using-virtual-credit-card-vcc) for implementation examples. ### 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: ```json { "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`,`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](/demand/docs/open-api/demand-api/orders/orders/preview) response would return something similar to: ```json { "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 (`1`and`2`) 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: ```json { "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](/demand/docs/open-api/demand-api/commonpayments/common/payments/cards) endpoint to match card IDs to card types. * See the [schedules](/demand/docs/payments/payments-timings/#payment-schedules) for more information. ### Car rental You can find all payment-related details in the `policies.payment` field of the order/preview responses. #### Example - Pay online now ```json { "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" } } } ] }, ``` ## Step 3 - Create the order After previewing payment details and confirming the traveller's choice, create the booking using the [/orders/create endpoint](/demand/docs/open-api/demand-api/orders/orders/create). * 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](/demand/docs/getting-started/sandbox) 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. ## Troubleshooting common issues | 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](/demand/docs/support/error-handling/payment-errors) for more examples Curious to know more? * For more tips and examples on how to preview and create an order, check the [Orders section](/demand/docs/orders-api/order-preview-create) * Learn about all the available [payment methods](/demand/docs/payments/payments-methods) and [timings](/demand/docs/payments/payments-timings). * You can also explore the different [payment models](/demand/docs/payments/models/accommodation-payment-models) for instructions, examples and best practices for payments.