Skip to content
/
Payment schedules
Last updated

Payment schedules

Understand how payment schedules represent when and how much is charged for a booking, using data returned in /orders/preview for accommodation and car rental (v3.2).

In this guide

  • What payment schedules are.
  • How schedules are structured in /orders/preview.
  • Key fields and concepts (dates, pay, display)
  • Accommodation vs car rental differences.
  • Worked examples.
  • UI and integration guidance.

What are payment schedules?

Payment schedules define the full breakdown of payments across a booking lifecycle.

A single order may involve multiple payment events, depending on:

  • Payment timing (see Payment timings guide)
  • Supplier or property policies.
  • Taxes, deposits, and extra charges.
  • Payment method rules.

Use payment schedules data to:

✓ Show exact payment breakdowns across time.
✓ Separate upfront vs later charges.
✓ Display all booking-related costs transparently.
✓ Prevent unexpected charges at checkout or fulfilment.

Payment schedule structure (orders/preview)

In /orders/preview, payment timing is expanded into a schedule of payment events, that defines when and how much is charged.

Dates

  • Each payment timing contains a dates array.
  • Each item in dates represents a single payment event.

Payment event structure

  • Each event includes:
    • at → when the payment occurs.
    • price (accommodation) or amount (car) → how much is charged.

Monetary values

Each monetary value may include:

  • pay → the actual amount that will be charged.
  • display → the amount shown to the traveller (may differ due to currency or rounding).

Key rules

  • A schedule may include multiple payment events.
  • The sum of all pay values represents the total collected via the API.
  • Some charges may be excluded due to legal or supplier constraints.

The sum of all payment events in dates represents the total amount collected through the API.

Extra charges

Some additional charges (for example, tourist taxes, deposits, etc) may not be included in this total and are paid at the property or pickup.

Payment method requirement

The method_required field indicates whether a payment method must be provided at booking time.

  • true → the traveller must provide a payment method (even if no charge is made at booking).
  • false → no payment method is required at booking.

Typical use cases

  • Guaranteeing bookings without upfront payment.
  • Deferred charging models.
  • Supplier-managed payments.

See the payment methods section for more details.

Extra charges

Some charges are handled separately due to legal or supplier rules.

Examples include:

  • Tourist taxes (legal requirement)
  • Security deposits.
  • Damage excess.
  • Fuel or service fees.

These:

  • May not be included in upfront payment events.
  • May appear as separate schedule entries.
  • May be collected at property or pick-up.

Refer to the Accommodation pricing section for more details.

Key difference: accommodation vs car

AspectAccommodationCar rental
Payment structureGrouped by timing objectAttached per price component
Data locationpayment.datesprice.*.pay/display.timing
Evaluation modelSchedule-levelField-level
ComplexityPolicy-drivenComponent-driven

Accommodation schedules in orders/preview

Accommodation schedules are returned in:

data.accommodation.general_policies.payment

Pay online now - example

In the following orders/preview response taken as example, there are 2 events "2025-01-18" (booking date) and "2025-02-10" (checkin date) together with price to pay each date:

{
 "accommodation": {
   "general_policies": {
     "payment": {
       "pay_online_now": {
         "method_required": true,
         "dates": [
           {
             "at": "2025-01-18",
             "price": {
               "accommodation_currency": 200.64,
               "booker_currency": 200.64
             }
           },
           {
             "at": "2025-02-10",
             "price": {
               "accommodation_currency": 5.14,
               "booker_currency": 5.14
             }
           }
         ]
       }
     }
   }
 }
}

Interpretation:

  • Full amount is charged at booking.
  • Any other additional payments such as extra charges are collected at checkin.

Pay online later - example

In this orders/preview response, there are 3 date events "2025-01-18" (booking date), "2025-02-02" (payment date) and "2025-02-10" (checkin date):

{
  "accommodation": {
    "general_policies": {
      "payment": {
        "pay_online_later": {
          "method_required": true,
          "dates": [
            {
              "at": "2025-01-18",
              "price": {
                "accommodation_currency": 0.00,
                "booker_currency": 0.00
              }
            },
            {
              "at": "2025-02-02",
              "price": {
                "accommodation_currency": 200.64,
                "booker_currency": 200.64
              }
            },
            {
              "at": "2025-02-10",
              "price": {
                "accommodation_currency": 5.14,
                "booker_currency": 5.14
              }
            }
          ],
          "methods": {
            "cards": [1, 2, 3, 4, ...]
          }
        }
      }
    }
  }
}

Interpretation:

  • At booking: no charge.
  • Before cancellation deadline: full amount is charged.
  • Check-in: extra charges (if applicable)

Not supported for certain credit card types (see payment timings details).

Pay at the property - example

In the following orders/preview response taken as example, there are 2 date items "2026-11-18" (booking date) and "2026-12-01" (checkin date):

{
  "accommodation": {
    "general_policies": {
      "payment": {
        "pay_at_the_property": {
          "method_required": true,
          "dates": [
            {
              "at": "2026-11-18",
              "price": {
                "accommodation_currency": 0.00,
                "booker_currency": 0.00
              }
            },
            {
              "at": "2026-12-01",
              "price": {
                "accommodation_currency": 205.78,
                "booker_currency": 205.78
              }
            }
          ],
          "methods": {
            "cards": [1, 2, 3, 4, ...]
          }
        }
      }
    }
  }
}

Interpretation:

  • At booking: no charge
  • At check-in: full amount is paid at the property.

Pay at the property with prepayment

There are cases when the property sets a prepayment policy, scheduling an instalment between the booking and checkin date.

Example:

{
  "general_policies": {
    "payment": {
      "pay_at_the_property": {
        "method_required": true,
        "dates": [
          {
            "at": "2026-11-18",
            "price": {
              "accommodation_currency": 0.00,
              "booker_currency": 0.00
            }
          },
          {
            "at": "2026-11-30",
            "price": {
              "accommodation_currency": 57.27,
              "booker_currency": 57.27
            }
          },
          {
            "at": "2026-12-01",
            "price": {
              "accommodation_currency": 76.29,
              "booker_currency": 76.29
            }
          }
        ]
      }
    }
  }
}

Interpretation:

  • At booking: no charge.
  • Before arrival: partial prepayment.
  • At check-in: remaining balance.

This flexible split is controlled by property policy.

Car rental payment schedules in orders/preview

Car rental does not group payments into timing objects.

Instead, timing is defined at field level.

Timing appears in:

  • price.base
  • price.total
  • extra_charges
  • policies.payment.dates (deposit, excess, etc.)
Important
  • Each monetary field must be evaluated independently.
  • There is no global schedule object for car rental payments.

Car rental - pay_online_now example

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": {
    "car": {
      "offer": 123456789,
      "currency": {
        "booker": "EUR",
        "payment": "EUR"
      },
      "price": {
        "base": {
          "display": {
            "value": 129.99,
            "currency": "EUR",
            "timing": "pay_online_now"
          },
          "pay": {
            "value": 129.99,
            "currency": "EUR",
            "timing": "pay_online_now"
          }
        },
        "extra_charges": [
          {
            "non_conditional": [
              {
                "charge_type": "one_way_fee",
                "amount": {
                  "display": {
                    "value": 15.0,
                    "currency": "EUR"
                  },
                  "pay": {
                    "value": 15.0,
                    "currency": "EUR",
                    "timing": "pay_online_now"
                  }
                }
              }
            ]
          }
        ],
        "total": {
          "value": 144.99,
          "currency": "EUR",
          "timing": "pay_online_now"
        }
      },
      "policies": {
        "cancellation": {
          "details": {
            "context": "before_pickup",
            "duration": "PT48H"
          },
          "type": "free_cancellation"
        },
        "damage_excess": {
          "amount": {
            "display": {
              "value": 1000.0,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            },
            "pay": {
              "value": 1000.0,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            }
          }
        },
        "deposit": {
          "amount": {
            "display": {
              "value": 200.0,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            },
            "pay": {
              "value": 200.0,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            }
          }
        },
        "fuel_policy": "return_same",
        "mileage": {
          "distance_limit": 300.0,
          "distance_unit": "kilometers",
          "type": "limited"
        },
        "payment": {
          "dates": [
            {
              "at": "2026-04-20",
              "amount": {
                "display": {
                  "value": 169.99,
                  "currency": "EUR",
                  "timing": "pay_online_now"
                },
                "pay": {
                  "value": 169.99,
                  "currency": "EUR",
                  "timing": "pay_online_now"
                }
              }
            }
          ]
        }
      },
...

Example scenario - A mixed payment order

In many rentals, the total cost is split. In the example below, the rental price is paid online, but the damage excess are handled at the desk.

{
  "price": {
    "total": {
      "value": 129.99,
      "currency": "EUR",
      "timing": "pay_online_now" 
    }
  },
  "policies": {
    "damage_excess": {
      "amount": {
        "display": {
          "value": 300.00,
          "currency": "EUR",
          "timing": "pay_at_pickup"
        },
        "pay": {
          "value": 300.00,
          "currency": "EUR",
          "timing": "pay_at_pickup"
      }
    }
  }
}

Interpretation:

Immediate Payment (pay_online_now)

  • The price.total shows €129.99.
  • Charged when booking online.
  • Since the timing is pay_online_now, the checkout UI should trigger a payment gateway (credit card, digital wallet, etc.) for this amount immediately.

Counter information (pay_at_pickup)

  • Not charged online.
  • Traveller must provide a card at the rental desk.
  • The damage.excess shows €300.00.
  • The UI should inform the traveller that they need to have a credit card available at the rental desk for a pre-authorisation, but this amount is not charged during the online checkout.
Curious to know more?

For additional information:

Previous page
Next page