Payment timings

Understand the available payment schedules and timings to better align with your business needs.

Payment timing overview

As an overall each payment type has different available timings:

Timings
`pay_at_the_property`	The traveller can pay at the property using the property accepted method.	Payment for the booking is usually due on the checkin date (unless there is a prepayment policy with instalments scheduled before the checkin date)
`pay_online_now`	The traveller pays online at the time of the booking, using one of the available payment methods.	Payment for the booking¹ is charged on the booking date.
`pay_online_later`	The traveller can pay online 48 hours before free cancellation period ends, using one of the available payment methods.	Payment for the booking¹ is charged 48 hours before free cancellation period ends.

¹ Extra charges (if any) are excluded.

Payment timing availability

The availability of these payment options depends on your specific payment scenario, including your payment agreements and the payment methods accepted by the property.

For example, pay_online_now and pay_online_later timings are available only if:

You have a partner agreement that permits their use (Otherwise, the default option is pay_at_the_property).
The property has enabled Online payments in our platform.

Check the available payment timings

Use the following endpoints to retrieve available payment timings for your specific scenario:

Endpoints	Response
/accommodations/search	Provides payment timings for each product retrieved.
/accommodations/availability	Returns available payment timings for the products in the response.
/orders/preview	Shows payment timings and schedules for the selected set of products in an order.

For best practices and examples, refer to the Search for accommodation and Orders sections.

Payment schedules

In the /orders/preview endpoint each payment timing object (pay_at_the_property, pay_online_now, pay_online_later) contains a dates field, with different dates for different sort of charges.

The dates field consists of 2 or 3 items, each of which shows the date (at) on which an amount of the total price of the booking must be paid.
This includes both the total booking price and any additional charges that might be collected separately.

Extra charges

In some countries, certain extra charges, like tourist taxes, must be paid at the property due to legal requirements.

These cannot be collected in advance when using the pay_online_now or pay_online_later timings, and will be separated in the payment schedule.

However, there are other extra charges that the property can collect online as part of their prepayment policy.

Examples

Find here some examples of common payment schedules:

Pay online now

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

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

Schedule	`at`	`price`
First item	The booking date (In this example 2023-12-18).	In `pay_online_now` timing, the total amount that must be charged for the stay without extra charges (if any). In this case 200.64. This amount is the total cost of the booking less charges that must be collected at the property, and will be paid using whichever payment method has been selected for the booking.
Second item	The checkin date for the booking (2024-01-10).	The extra charges amount that will be collected at the property at checkin date using one of the payment methods they accept. In this case 5.14.

Pay online later

In this orders/preview response, there are 3 date items "2023-12-18" (booking date), "2024-01-09" (payment date) and "2024-01-10" (checkin date):

"accommodation": {

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


                   }

The dates object offered for the pay_online_later timing shows that:

Schedule	`at`	`price`
First item	The booking date (In this example 2023-12-18).	Will always be 0 for this payment timing.
Second item	The date on which payment will be charged. This is either when the free cancellation period ends, or 48 hours before the checkin date. In this example 2024-01-09.	The amount to be charged, in this case 200.64.
Third item	The checkin date for the booking.	The extra charges amount that will be collected at the property at checkin date. In this case 5.14.

Pay at the property

Without prepayment

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

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

Schedule	`at`	`price`
First item	The booking date (In this example 2023-12-18).	In `pay_at_the_property` timing, the total amount that must be charged at the moment of the booking is always 0.00 (unless there are prepayment policies).
Second item	The checkin date for the booking (2024-01-10).	The total amount that must be charged for the stay including extra charges (if any). This is collected at the property at checkin date using one of the accepted payment methods. In this case 205.78.

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": "2024-10-24",
                           "price": {
                               "accommodation_currency": 0.00,
                               "booker_currency": 0.00
                           }
                       },
                       {
                           "at": "2024-11-10",
                           "price": {
                               "accommodation_currency": 57.27,
                               "booker_currency": 57.27
                           }
                       },
                       {
                           "at": "2024-11-18",
                           "price": {
                               "accommodation_currency": 76.29,
                               "booker_currency": 76.29
                           }
                       }
                   ],

In this example there are 3 date items for different instalments:

Schedule	`at`	`price`
First item	When the order request is sent (In this example 2024-10-24).	Here, the total amount that must be charged for the booking is 0.00
Second item	When the first instalment is due (2024-11-10). This item is not returned if there is no prepayment policy set by the property.	The amount that must be charged before checkin, in this case 57.27. This is collected online using one of the accepted payment methods.
Third item	The checkin date for the booking (2024-11-18)	The final instalment that will be collected at the property at checkin date. In this case 76.29.

Curious to know more?

For additional information on supported payment methods, use cases, and guidance on creating order requests, refer to: