Use these guidelines to correctly display payment information in your application using data from the Demand API.
Payment information is returned across multiple endpoints, including:
- /search and /availability → payment timing overview.
- /orders/preview → full payment schedule with detailed breakdown (dates and amounts).
Use this data to clearly communicate:
✓ What the traveller pays now.
✓ What the traveller pays later.
✓ What is paid at the property or pick-up.
✓ Any deposits, guarantees, or extra charges.
Accurate presentation of payment information:
- Improves booking conversion.
- Reduces customer support queries.
- Builds traveller trust.
- Prevents unexpected charges at fulfilment.
Example
A car rental shows €129.99 online, but also requires a €300 deposit at pick-up.
If the deposit is not clearly displayed:
- Travellers may abandon checkout.
- Support requests increase.
- on-site disputes may occur.
The same applies to accommodation bookings with property-collected charges.
Use timing to determine how payment is presented in the UI.
| Timing | Recommended UI label |
|---|---|
pay_online_now | Pay now |
pay_online_later | Pay later |
pay_at_the_property | Pay at property |
pay_at_pickup | Pay at pick-up |
pay_partial_online | Pay part now |
Avoid exposing raw API values directly.
When using /orders/preview, always display all payment events from the dates array.
Each event contains:
at- When the payment occurs.price(accommodation) oramount(car) - The amount to be charged.
Group payments into:
- Upfront payment.
- Pre-arrival payment (if any)
- On-site payment (check-in or pick-up)
Do not assume a single payment event.
Always distinguish between:
- Charges paid online.
- Charges paid at property or pick-up.
- Deposits and guarantees.
Do not merge these into a single total without explanation.
Each monetary value may include:
| Price | Description | Rules |
|---|---|---|
pay | Actual amount charged. | Use pay for all backend charging logic. |
display | Amount shown in the UI in Booker's currency. | Use display for UI presentation only. |
They may differ due to:
- Currency conversion.
- Rounding rules.
- Supplier-specific pricing formats.
Some charges are not included in upfront payment totals since they are not paid online.
These may include:
- Tourist taxes
- Security deposits
- Damage excess
- Service or local fees.
Display rules: ✓ Always show them separately from base price.
✓ Clearly indicate when and where they are paid.
✓ Do not merge them into upfront totals unless they are charged online.
Payment information must remain consistent across:
- Search results.
- Product page.
- Checkout / order preview.
Differences between endpoints (e.g. /availability vs /orders/preview) must be handled carefully to avoid confusion.
API data:
€129.99 → pay_online_now €300 → pay_at_pickup (deposit)
Recommended UI:
- Pay now: €129.99
- Pay at pick-up: €300 deposit (not charged now)
API data:
- Booking: €0
- Before cancellation deadline: €200
- Check-in: €5 (taxes)
Recommended UI:
- Pay later: €200
- Pay at property: €5
API data:
- Booking: €0
- Check-in: €205
Recommended UI:
- Pay at property: €205
If payment schedule data is incomplete:
- Do not infer or estimate missing payments.
- Avoid displaying misleading totals.
- Fall back to timing-only messaging (e.g. “Pay at property”).
- Hiding deposits or extra charges.
- Showing only the upfront amount.
- Assuming one payment per booking.
- Mixing
displayandpayinconsistently. - Showing incorrect timing labels.
- Exposing unsupported payment options.
Before going live, ensure:
- All
datesentries are displayed. - All payment timings are mapped to UI labels.
- Deposits and extra charges are clearly separated.
- Totals match the sum of displayed payment events.
- Payment information is consistent across all pages.
For additional information: