X
Our new Developer Portal is here!
The latest version of our Demand API (V3.1) is now available.
Update now for improved functionality and access to newly added endpoints.
Take me there
How to use Online Payments
### Online Payments
## Introduction
There are 4 possible options when making payments on the API.
- Agency - The guest is liable to pay the property.
- Payment Instructions - Booking.com will send a voucher to the property informing them of the charges that need to be made.
- Payment Instructions with AirPlus (*only applicable for Corporate Travel*) - This is identical to Payment Instructions however Booking.com can generate the virtual card using your Airplus AIDA account.
- Online Payments - Booking.com will charge the card sent via the API and pay the property on your behalf according to the policy.
## Working with Online Payments
Online payments gives you access to exclusive payment properties and the ability to pay on behalf of a traveller at the property.
**Get Online Payments properties**
Not all properties support Online Payments. Only properties that have `"pay_now: true"` in the `/hotels` static information can be paid with Online Payments.
There are two types of properties that accept Online Payments:
*- Exclusive properties*: only support Online Payments.
*- Hybrid properties*: support both Online Payments and Agency.
To use Online Payments:
* for versions 2.9 and later, ensure to use the parameter `"payment_method=vcc"` (if the credit card is a virtual credit card not requiring 3D Secure) or `"payment_method=cc_sca"` (if the credit card requires 3D Secure: the Strong Customer Authentication tokens will need to be present too) in your `/processBooking` calls.
* for versions 2.0 through 2.8, ensure to use the parameter `"pay_now=1"` in your `/processBooking` calls.
## Making a booking with an Exclusive property
Exclusive properties only support Online Payments.
**- Step 1:** Retrieve Static content from the `/hotels` endpoint as you normally would and follow the `payment_options` response.
`"pay_now: true"` , `"pay_at_property: false"` would indicate a property that is bookable exclusively with Online Payments.
Sample call:
```
curl --request GET 'https://distribution-xml.booking.com/2.6/json/hotels?hotel_ids=3882292&extras=payment_details'
```
Response:
```
result: [
{
room_data: [ ],
hotel_id: 3882292,
hotel_data: {
payment_options: {
pay_at_property: false,
pay_now: true
},
payment_details: [
{
payable: true,
cvc_required: true,
payment_id: 18,
bookable: false
},
{
payment_id: 2,
bookable: true,
payable: false,
cvc_required: true
},
{
cvc_required: true,
payable: false,
payment_id: 3,
bookable: true
},
{
bookable: true,
payment_id: 1,
payable: false,
cvc_required: true
}
]
}
}
]```
**- Step 2:** Use `/hotelAvailability` and `/blockAvailability` endpoints as you would regularly do to check availability and price of properties. Ensure that `“pay_now = trueâ€` in the call response.
Sample call:
```
https://distribution-xml.booking.com/2.6/json/blockAvailability
```
(add your regular parameters)
**- Step 3:** Make bookings in `/processBooking`
* for versions 2.9 and later, with parameter `"payment_method=vcc"` and pass a Virtual Credit Card
* for versions 2.9 and later, with parameter `"payment_method=cc_sca"` and pass a credit card requiring 3D Secure, plus the Strong Customer Authentication tokens
* for versions 2.0 through 2.8, with optional (see below) parameter `"pay_now=1"` and pass a Virtual Credit Card
to ensure the payment will be successfully processed.
Sample call:
```
https://secure-distribution-xml.booking.com/2.6/json/processBooking
```
(add your regular parameters and your VCC info)
**- Step 4**: Partner charges guests with any payment on their end.
**Cancellation:** Use `/cancelBooking` endpoint as regularly to cancel Pay Now Booking.(*Refund will go back to the card used in processBooking depending on the policy booked). Partner then needs to refund their guest.
Sample call:
```
https://secure-distribution-xml.booking.com/2.6/json/cancelBooking
```
***Note:*** * The parameter "pay_now=1" is optional for Exclusive properties and may be omitted. If you only want to book Exclusive content and are not interested in Hybrid content, then do not pass the parameter "pay_now=1" in your /processBooking requests.*
## Making a booking with a hybrid property
Hybrid properties support both Online Payments and Agency Payments.
**- Step 1:** Retrieve static content from the `/hotels` endpoint as you normally would and follow the `payment_options` response.
`"pay_now = true"`, `"pay_at_property = true"` would indicate a property that offers hybrid payment options (Online Payments and Agency).
Sample call:
````
https://distribution-xml.booking.com/2.6/json/hotels?hotel_ids=91121&extras=payment_details
```
**- Step 2:** Use `/hotelAvailability` and `/blockAvailability` endpoints as you would regularly do to check availability and price of properties.
Sample call:
```
https://distribution-xml.booking.com/2.6/json/blockAvailability
```
If the property supports online payments, the output in `/blockAvailability` will also contain as per below:
*Sample result:*
`<can_pay_now>1</can_pay_now>`
`"can_pay_now": true`
*- Step 3:* Make bookings with `/processBooking`,
* for versions 2.9 and later, with parameter `"payment_method=vcc"` and pass a Virtual Credit Card
* for versions 2.9 and later, with parameter `"payment_method=cc_sca"` and pass a credit card requiring 3D Secure, plus the Strong Customer Authentication tokens
* for versions 2.0 through 2.8, with parameter `"pay_now=1"` (mandatory) and pass a Virtual Credit Card
to ensure the payment will be successfully processed.
Sample call:
```
https://secure-distribution-xml.booking.com/2.6/json/processBooking?pay_now=1
```
(add your regular parameters and your VCC info)
**- Step 4:** Partner charges guests with any payment on their end.
**Cancellation:** Use `/cancelBooking` endpoint as regularly to cancel Online Payments bookings. Partner then needs to refund their guest.
**Modifications:** It should be the regular flow with modification end points. If the dates are changed the appropriate action would be taken in regards to payment - just like with the regular credit cards.
Sample call:
```
https://secure-distribution-xml.booking.com/2.6/json/cancelBooking
```
## Payments information
**Confirming a booking is Online Payments**
Given a booking is Online Payments, in `/bookingDetails`, under the node `direct_payment_info`, the following information will be displayed in the output:
```
"amount":
{ "currency":
"Payment_amount":
"Payment_amount_paid":
"Percent_paid":}
```
**Cancellations**
Given an Online Payments booking is cancelled and the property will offer partial or full waiver, this is now visible in `/bookingDetails` in the output cancellation_fee
To see the reason for cancellation the partner must pass `"extras=status_details"` (version 2.6 or higher)
**Handling Cancellations and Refunds**
Given the partner cancels the booking, then there are two scenarios:
- Cancellation without fees: the full reservation amount will be refunded to the partner's VCC.
- Cancellation with fees (Non-Refundable and Partially Refundable Policy): The partner's VCC will be partially refunded.
The partner will need to call `/bookingDetails` for those reservations to see if the cancellation is finalised and then follow the refund flow.
***Note: *** *No refund will be given for non-refundable reservations cancelled via the Manage My Booking page or `/cancelBooking` endpoint.*
**How to test:**
`/bookingDetails` will provide the partner with the information required to find out the cancellation type and the refund amount by combining ‘status’ and ‘cancellation_fee’.
Partners need to pass the following to `/bookingDetails` for cancelled bookings:
```
extras=status_details
extras=no_show
cancellation_fee
```
**`/bookingDetails` Outputs**
A partner can use the following reference to understand the action to take for each `/bookingDetails` status and `cancellation_fee`:
**Status:** Cancelled by hotel ; **Cancellation Fee:** "0" OR no response
**Partner's Action:** Partner must refund guest for full amount (Partner should never cancel this reservation and should let Customer Service resolve the issue).
**Status:** Cancelled by guest ; **Cancellation Fee:** >0
**Partner's Action:** Guests are liable for the cancellation fee. Therefore partner must refund accordingly: Refund = Reservation price - cancellation fee.
**Status:** Cancelled by guest ; **Cancellation Fee:** "0" OR no response
**Partner's Action:** Partner must refund guest for full amount.
**Status:** No Show, **Cancellation Fee:** >0
**Partner's Action:** Guests are liable for the cancellation fee. Therefore partner must refund accordingly: Refund = Reservation price - cancellation fee.
**Status:** No Show ; **Cancellation Fee:** "0" OR no response
**Partner's Action:** Partner must refund guest for full amount.
***Note: *** *After confirmation by customer support, the new cancellation fee will display ~3hours later on `/bookingDetails`. Refunds take **10** business days to reflect on Virtual Credit Card*
