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*