This guide explains how payment data flows through the Demand API and how to integrate payments into your booking flow. It applies to both accommodation and car rental products.
Payment information is distributed across multiple endpoints in the booking flow.
Use different endpoints to:
✅ Discover payment options.
✅ Retrieve payment requirements.
✅ Preview the full payment breakdown.
✅ Create a booking with the correct configuration.
| Endpoint | Use it to ... |
| /search and /availability | Retrieve high-level payment availability and payment timings for a product. |
| /details | Retrieve supported payment methods for the selected product. |
| /orders/preview | Full payment breakdown and schedule. |
| /orders/create | Complete bookings with correct payment configuration. |
A typical integration follows this sequence:
- Search for available products.
- Retrieve payment options and methods.
- Preview the full order and payment breakdown.
- Create the order using selected payment configuration.
Use
- /search
- /availability
These endpoints return high-level payment availability, including:
- Available payment options.
- Whether a product is eligible for specific payment flows.
At this stage, payment data is indicative only.
Use
- /details
This endpoint returns:
- Supported payment methods per product.
- Card types or alternative payment options (if applicable).
This determines how a booking can be paid or guaranteed.
Use
- /orders/preview
At this stage, you must treat the response as authoritative for checkout behaviour.
It returns the complete payment configuration, including:
- When payments occur - Payment timings
- How payments are split over time - Payment schedules (dates)
- Whether a payment method is required - Payment methods
- How much is charged.
Always treat /orders/preview as the source of truth for checkout
Use
- /orders/create
This finalises the booking.
Ensure:
- The selected payment option matches orders/preview.
- Required payment methods are included (if applicable)
- Payment structure is unchanged from orders/preview.
| Core integration rule | Guidance |
|---|---|
| Do not hardcode payment behaviour |
|
| Always validate against /orders/preview |
|
| Do not assume a single payment event per order |
|
| Ensure consistency between preview and create |
|
If multiple payment options are returned:
- Display all available options.
- Allow the traveller to choose one.
- Ensure only one timing is used in /orders/create.
Payment data may vary slightly between endpoints due to:
- Availability updates.
- Supplier policy changes.
- Dynamic pricing rules.
Always prioritise /orders/preview for checkout logic.
Before going live:
- Test full payment flows in sandbox (for accommodation)
- Validate real payment method behaviour where required.
- Ensure order creation matches orders/preview exactly.
| Issue | Cause | Recommendation |
|---|---|---|
| 400 – missing payment method | In accommodation method_required is true, but no method provided. | Use a supported VCC or card in /orders/create |
| Unexpected payment 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. |
✅ Payments are driven entirely by API responses.
✅ /orders/preview is the authoritative checkout model.
✅ Payment behaviour is not static or hardcoded.
✅ Multiple payment events per booking are expected.
✅ Method + timing + schedule must always be aligned at checkout.