# Get started with payments

**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 overview

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.

![How to use payments](/assets/overview_how-to-use-payments.9ed2c436d1bf5d700e2736fb42facfd10ad1cb9fc002df04827a802171af5532.fe580a34.jpg)

| 
| **Endpoint** | **Use it to ...** |
| /search and /availability | Retrieve high-level payment availability and [payment timings](/demand/docs/payments/payments-timings/) for a product. |
| /details | Retrieve supported [payment methods](/demand/docs/payments/payments-methods/) for the selected product. |
| /orders/preview | Full payment breakdown and [schedule](/demand/docs/payments/payments-schedules). |
| /orders/create | Complete bookings with correct payment configuration. |


## Payment flow

A typical integration follows this sequence:

1. Search for available products.
2. Retrieve payment options and methods.
3. Preview the full order and payment breakdown.
4. Create the order using selected payment configuration.


### Step 1 - Search available products

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**.

### Step 2 - Retrieve payment methods

Use

* /details


This endpoint returns:

* Supported [payment methods](/demand/docs/payments/payments-methods/) per product.
* Card types or alternative payment options (if applicable).


This determines **how a booking can be paid or guaranteed**.

### Step 3 - Preview payment breakdown

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](/demand/docs/payments/payments-timings/)
* How payments are split over time - [Payment schedules (dates)](/demand/docs/payments/payments-schedules)
* Whether a payment method is required - [Payment methods](/demand/docs/payments/payments-methods/)
* How much is charged.


Always treat /orders/preview as the **source of truth for checkout**

### Step 4 - Create the order

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 rules

| Core integration rule | Guidance |
|  --- | --- |
| **Do not hardcode payment behaviour** | * Payment behaviour is dynamic and driven by supplier configuration.
* It must not be assumed or fixed in the integration.

 |
| **Always validate against /orders/preview** | * This endpoint defines the final payment structure, required constraints, and authoritative checkout behaviour.

 |
| **Do not assume a single payment event per order** | * A booking may include multiple charges, split payments, deposits, or guarantees.

 |
| **Ensure consistency between preview and create** | * /orders/create must strictly match /orders/preview in payment timing selection, required payment method rules, and schedule structure.

 |


### Handling multiple payment options

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.


### Cross-endpoint consistency

Payment data may vary slightly between endpoints due to:

* Availability updates.
* Supplier policy changes.
* Dynamic pricing rules.


> ![tip](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) Always prioritise /orders/preview for checkout logic.


## Testing recommendations

Before going live:

* Test full payment flows in [sandbox](/demand/docs/getting-started/sandbox) (for accommodation)
* Validate real payment method behaviour where required.
* Ensure order creation matches orders/preview exactly.


## Troubleshooting

| 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. |


## Key takeaways

✅ 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.

## Next steps

Curious to know more?
* [Payment errors guide](/demand/docs/support/error-handling/payment-errors)
* [Payment methods](/demand/docs/payments/payments-methods)
* [Payment timings](/demand/docs/payments/payments-timings)
* [Displaying payments](/demand/docs/payments/payments-display)
* [Accommodation payment models](/demand/docs/payments/payments-examples).