# Displaying payments

**Use these guidelines to correctly display payment information in your application using data from the Demand API.**

## Overview

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.

### Why it matters

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.

## Payment mapping rules

### Map payment timing to UI labels

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.

## Payment breakdown rules (orders/preview)

When using /orders/preview, always display all payment events from the `dates` array.

Each event contains:

* `at` - When the payment occurs.
* `price` (accommodation) or `amount` (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.

### Separate payment types clearly

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.

### Display vs pay model

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.


### Clearly communicate extra charges

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.

### Maintain consistency across the booking flow

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.

## Display examples

### Example: Split payment (car rental)

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


### Example: Pay later (accommodation)

**API data:**

* Booking: €0
* Before cancellation deadline: €200
* Check-in: €5 (taxes)


**Recommended UI:**

* Pay later: €200
* Pay at property: €5


### Example: Pay at property

**API data:**

* Booking: €0
* Check-in: €205


**Recommended UI:**

* Pay at property: €205


## Handling missing or partial data

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


## Common mistakes to avoid

* Hiding deposits or extra charges.
* Showing only the upfront amount.
* Assuming one payment per booking.
* Mixing `display` and `pay` inconsistently.
* Showing incorrect timing labels.
* Exposing unsupported payment options.


## Implementation checklist

Before going live, ensure:

* All `dates` entries 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.


Curious to know more?
For additional information:

* [Payment schedules](/demand/docs/payments/payments-schedules)
* [Payment timings](/demand/docs/payments/payments-timings)
* [Payment methods](/demand/docs/payments/payments-methods)