Payment timings

Learn about the available payment schedules and timings so you can understand timelines applied to your business scenario.

Payment timing

As an overall each payment type has different available timings:

¹ Excluding extra changes (if any)

However, not all options may be available for your payment scenario, as different combinations of payment timings and payment methods provide different payment options for how and when to pay for a booking.

Which payment options are available depends upon the particular payment scenario you are using, and on the payment timings and methods available for the chosen property.

Check the available payment timings

Call the following endpoints to see information about available payment timings for your specific scenario:

Refer to the Quick guide -- for examples of responses and initial instructions on how to check the available payments options, including timings and schedules.

Refer to the Use cases section -- for instructions and examples on how to define timings when creating your order request, according to your business scenario.

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.

• It shows how and when the total price of the booking must be paid, as well as when extra charges (if any) must be paid.
• The dates object contains 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.

Extra charges

In some countries, by law, there are certain extra charges that must be paid at the property - for example, tourist taxes. These charges cannot be collected in advance when using the pay_online_now or pay_online_later timings, so are broken out separately in the payment schedule.

The following illustration shows how to interpret the payment schedule for each payment timing, and charges.

Examples

Find here some examples of the 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
                               }
                           }
                       ],

• Dates: The dates object offered for the pay_online_now timing shows how and when the total price of the booking must be paid:

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


                       }

• Dates: Contain three payment schedule items, showing how and when the total price of the booking must be paid.

• 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 taken: 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 to your provided VCC. 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 property

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,...]
                       }
                   }
               }
            },
           ...

• Dates: The dates object for the pay_at_property timing shows how and when the total price of the booking must be paid:

  Schedule	at	price
  First item	The booking date (In this example 2023-12-18).	In pay_at_property timing, the total amount that must be charged at the moment of the booking is always 0.00
  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.