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*
