# 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 [/accommodations](/demand/docs/open-api/demand-api/accommodations/) and [/orders](/demand/docs/open-api/demand-api/orders/) endpoints. Use these endpoints within your application flow to: ✅ Display payment timings and methods to travellers. ✅ Process their chosen payment method during booking. ![How to use payments](/assets/overview_how-to-use-payments.df968ceea5dfe1a4c78a2845595a5bcbb1a54acf1e786326da0178eb0f56f824.fe580a34.png) Before diving into implementation details, ensure you're familiar with the available [timings](/demand/docs/payments/payments-timings/), [schedules](/demand/docs/payments/payments-timings/#payment-schedules) and [payment methods](/demand/docs/payments/payments-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. | | **Endpoint** | **Use it to ...** | | [/accommodations/search](/demand/docs/open-api/demand-api/accommodations/accommodations/search) [/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) | Retrieve supported [payment timings](/demand/docs/payments/payments-timings/) available for a product. | | [/accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details) | Retrieve accepted [payment methods](/demand/docs/payments/payments-methods/) (payment cards and/or cash) for the selected accommodation. | 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 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 [Filtering and sorting guide](/demand/docs/accommodations/filter-sorting) for details. ### 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/payments-examples#creating-orders-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](/demand/docs/open-api/demand-api/orders/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. ## 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 use cases](/demand/docs/payments/payments-examples) for instructions, examples and best practices for payments.