Payments FAQs

A CVC (Card Verification Code) is the security code printed on a payment card. The card issuer can use it to help verify a card payment.

• If a payment fails with issuer_cvc_check_failed, check that the CVC was entered correctly and matches the card.
• For accommodation orders, request the payment extra from /accommodations/details to receive payment.cvc_required and payment.amex_cvc_required.
• For a standard card payment, provide the CVC in payment.card.cvc when required by the selected payment flow.
• MOTO exception: for a MOTO payment, omit the CVC even if cvc_required or amex_cvc_required is true.

Follow the card requirements for the selected payment model when creating or modifying an order.

In the response, data.accommodation.general_policies.payment contains an object for each available payment timing. Its method_required value tells you whether you must provide a payment method to book using that timing.

• true: a payment method is required for that timing.
• false: a payment method is not required to create the booking using that timing. This does not mean that no payment will be due later.

Use the methods object alongside method_required to see which payment methods are available. This field is defined for accommodation previews; it is not returned for car previews.

The answer depends on when the traveller pays:

• Online payment: use /orders/preview. For the selected timing, check data.accommodation.general_policies.payment.<timing>.methods.cards.
• Payment at the property: request the payment extra from /accommodations/details. The response lists property payment methods under data[].payment.methods.cards and virtual cards under data[].payment.methods.virtual_cards. It may also include data[].payment.methods.cash.

Use /common/payments/cards to map card IDs to card names.

Call /cars/terms-and-conditions for the selected car offer. In data.key_info, check:

• deposit.accepted_cards for card types accepted for the security deposit.
• common.credit_cards_allowed and common.debit_cards_allowed for the supplier's general credit and debit card rules.

For an offer payable at pickup, also check credit_card_required in the car search or availability result. This indicates whether the supplier requires a credit card as a guarantee.

Yes, when the selected offer is payable at pickup, the offer returns credit_card_required: false, and its accepted price has no amount payable online. In that case, omit payment from /orders/create. If credit_card_required is true, provide the payment and card details required for the offer.

Do not decide whether to omit payment from payment.timing alone. Check the selected offer and the accepted price in the order token. This cardless flow is available in both v3.2 and v3.3.

PayPal is not listed as a payment method in the v3.2 or v3.3 order payment schema. Check the payment methods returned for the selected order and the Payments guide for methods enabled for your integration.

Cryptocurrency is not listed as a payment method in the v3.2 or v3.3 order payment schema. Check the payment methods returned for the selected order and the Payments guide for methods enabled for your integration.

SCA requirements depend on applicable regulations and the payment. The v3.2 and v3.3 API schemas support card authentication data and SCA exemptions in the order payment request; they do not define country coverage.

For eligibility and setup, see Credit card + Strong Customer Authentication (SCA) and the payment model available to your integration.

Check the returned payment error first. Depending on the error, correct the card or authentication information, retry the payment, or ask the traveller to authenticate again and provide new authentication data. Do not reuse authentication data that the issuer or payment flow has invalidated.

See payment-related errors for error-specific guidance.

Access to a payment model may require a separate agreement and account configuration. Confirm the requirements with your Account Manager before implementing it. See the prerequisites in the Credit card + SCA payment model.

If a card is replaced, expired or otherwise no longer valid for the transaction, obtain fresh card and authentication data through the applicable payment flow. Authentication data is associated with the card and transaction for which it was created.

The v3.2 and v3.3 schemas do not define a separate SCA-token field. For a card payment, the request can include authentication data under payment.card.authentication.3d_secure or an eligible exemption under payment.card.authentication.sca_exemption. The configured payment model determines which party collects and supplies that data. See the relevant payment model documentation.

Request the payment extra from /accommodations/details. The VCC card IDs accepted by the property are returned in data[].payment.methods.virtual_cards. Use /common/payments/cards to map an ID to a card name.

See the corporate payment instructions guide for the order flow.

For an AirPlus accommodation order, provide the required 12-digit AirPlus number as a string. DBI fields such as accounting_code, accounting_unit and project_number are optional strings of 1 to 17 characters.

See Using AirPlus VCC for prerequisites and examples.

The accommodation preview can indicate AirPlus availability with methods.airplus for each payment timing. AirPlus is available only when enabled for your integration. Car rental orders that require payment details support card payment; the car payment schema does not list AirPlus.

See Using AirPlus VCC for prerequisites and examples. Use the preview response to determine whether AirPlus is available for the selected accommodation order.

Use the authorisation form for supported corporate payment flows where your company pays the property with its own VCC and needs to give the property charging instructions. In /orders/create, send the company name and authorisation form details in business_information; the form can include chargeable_items.

When the request includes an authorisation form, the response can return data.payment.authorisation_form_url. The link is valid for seven minutes, so retrieve and share it promptly.

See Pay at the property with your own VCC for the complete flow.

An insufficient funds error means the card issuer or payment provider declined the payment because the available funds or credit were insufficient.

An invalid amount error means the amount submitted for payment could not be processed as expected, for example because it does not match the authorised amount. The order creation request does not take a separate price; it uses the order_token returned by /orders/preview. Do not change or reconstruct the amount outside the supported payment flow.

Check the payment error details and the order token flow, then see payment-related errors for next steps.

For accommodation:

• /accommodations/details returns property-level timings in data[].payment.timings when you request the payment extra.
• /accommodations/search and /accommodations/availability return product-level timing information under each product's policies.payment.timings.
• /orders/preview returns the available timings and payment schedules for the selected order in data.accommodation.general_policies.payment.

Accommodation timings are pay_online_now, pay_online_later and pay_at_the_property.

For car rental, check the selected offer's policies.payment.timing in the car search or availability response. Car timings include pay_online_now, pay_at_pickup and pay_partial_online_now. To filter car search results, use the payment.timings input filter described in Filtering by payment timing.

See Payment timings for more information.

No. Accommodation and car rental use different timing values.

Use the values returned for the selected product or order. For car rentals, pay_partial_online_now means that part of the payment is made online at booking and the balance is paid at pickup.

It means meeting the booking requirements for the selected rate and payment timing. Depending on the offer, this may require a payment method, an online payment, or no payment method at booking. Check method_required, methods and dates in the /orders/preview response.

For pay_at_the_property, the payment schedule may show no online charge at booking and a later amount due at the property. Follow the selected corporate payment model for card handling and property instructions.

In /orders/preview, check data.accommodation.general_policies.payment.pay_online_later.dates. Each entry contains at (the date of an instalment) and price (the amount for that instalment).

Some charges, such as local taxes, may be payable at the property. Review the returned schedule and charge breakdown for the selected order.

See the Payment schedules guide for more detail.

Card handling depends on the payment model. In Booking.com-managed pay-at-the-property flows, Booking.com manages the payment and applicable late-cancellation or no-show charges, so the property does not receive the traveller's card details through the Demand API. The property collects the amount due when the traveller arrives.

For a corporate flow using your own VCC, follow the separate payment instructions flow.

For an online payment, set payment.include_receipt to true in /orders/create. If a receipt is available, the response includes data.payment.receipt_url.

For an accommodation order paid later, /orders/details/accommodations can return a credit_slip_number when one is available. Check the order details when payment is due. For a car rental booking paid at pickup, request the receipt from the rental supplier.

Commission data may be unavailable if commission is not enabled for your account or if the final amount has not yet been calculated. A cancelled order may also return null commission values.

For accommodation orders, the details response uses actual_amount and estimated_amount. Car commission field names depend on the car details endpoint and version; see the version-specific sections below. Retrieve current order details from the relevant endpoint.

Use the relevant /orders/details endpoint to retrieve order information. The response includes a booker object; the exact fields depend on the travel service and endpoint. For car endpoint differences, see the version-specific sections below.

Follow the test instructions for your payment model and environment. The API schemas do not specify test card numbers, whether a test payment moves real funds, or an automatic refund schedule. Do not assume that a production payment will be refunded automatically.

See the Payments quick guide for the current testing process. Car order creation is not available in the Demand API sandbox in either version; use the environment stated in the relevant API reference for car order testing.

Use /orders/details/cars. In v3.3, this endpoint provides the enriched, up-to-date car order details that were returned by /orders/details/cars/live in v3.2. The v3.2 /orders/details/cars/live endpoint is not available in v3.3.

The v3.3 car details response uses actual_commission_amount and estimated_commission_amount for car commission values.

Set extras.include_invoice to true in the /orders/details/cars request. The response can include invoice documents under data[].invoices, with separate invoice_document and electronic_invoice entries.

Each document has its own status. When a document URL is available, download it promptly: URLs are valid for 10 minutes and must not be cached. If a document is temporarily unavailable or unavailable, call the endpoint again later as appropriate.

Use /orders/details/cars for standard car order details. For enriched, live post-booking details such as current status, supplier and driver information, use /orders/details/cars/live. The live endpoint is specific to v3.2; its live functionality is available through /orders/details/cars in v3.3.

The v3.2 live car details response uses actual_commission_amount and estimated_commission_amount for car commission values.

The v3.2 car details schemas do not define the extras.include_invoice request or invoice-document response available in v3.3. Use your supplier's invoicing process for car rental invoices in v3.2.