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 Payment Instructions
### Payment Instructions
## 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 Payment Instructions
Payment Instructions gives you the ability to pay on behalf of a traveler at the property.
**Get available properties**
In order to get a list of hotel ids available on specific check-in, check-out dates and country query `/hotelAvailability` endpoints.
*Example:*
```
curl --request GET 'https://distribution-xml.booking.com/2.x/json/hotelAvailability?checkin=yyyy-mm-dd&checkout=yyyy-mm-dd&city_ids=-1565670&room1=A,A&guest_country=nl'
```
**Get available payment methods**
Not all properties have the ability to charge a virtual card. Only properties that have the following payment types available in the hotel static information can be paid with Payment Instructions.
**39:** MasterCard virtual card
**74:** Visa virtual card
**75:** American Express Virtual Card
*Notes:*
- A booking request will fail and an error will return with following message: "The requester tried to prepay for a hotel, and the hotel does not accept prepayments." if you are attempting to book a property that does not accept virtual cards.
- Select the virtual credit card that is being flagged as **"payable=true"**.
- When making payment select the relevant payment type depending on the virtual card type created.
- American Express Virtual Card
- Visa virtual card
- MasterCard virtual card
*Example:*
```
curl --request GET 'https://distribution-xml.booking.com/2.x/json/hotels?hotel_ids=35569&extras=payment_details'
```
**Getting rooms available on a property**
In order to know rooms available in a hotel a query to `/blockAvailability` endpoints is needed, block_id is a mandatory parameter to use `/processBooking` endpoint.
*Example:*
```
curl --request GET 'https://distribution-xml.booking.com/2.x/json/blockAvailability?checkout=yyyy-mm-dd&checkin=yyyy-mm-dd&hotel_ids=35569&guest_cc=NL&guest_qty=1'
```
**Making a booking**
In order to pass the payment instructions to the hotel you have to pass the following parameters.
- **"guest_names"**
- **"vc_company_for_auth_form"**
*Notes: *
- In the past **"options=prepayment"** was required this is not required anymore. (NEW)
- If there is more than one guest in the reservation, then the company name will be printed on the card and not a list of the guest names.
*Example:*
```
curl --request POST 'https://secure-distribution-xml.booking.com/2.x/json/processBooking' \
--header 'Content-Type: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'hotel_id=35569' \
--data-urlencode 'show_test=1' \
--data-urlencode 'checkin=yyyy-mm-dd' \
--data-urlencode 'checkout=yyyy-mm-dd' \
--data-urlencode 'cc_number=xxxxxxxxxxxxxxxx' \
--data-urlencode 'booker_firstname=TestFirstName' \
--data-urlencode 'booker_lastname=TestLastName' \
--data-urlencode 'vc_company_for_auth_form=SomeCompany' \
--data-urlencode 'affiliate_id=123456' \
--data-urlencode 'block_ids=3556901_95156930_2_2_0' \
--data-urlencode 'incremental_prices=191' \
--data-urlencode 'booker_country=nl' \
--data-urlencode 'booker_email=booker.name@testemail.com' \
--data-urlencode 'booker_telephone=+3123456789' \
--data-urlencode 'extras=auth_form_url' \
--data-urlencode 'booker_address=TestAdress' \
--data-urlencode 'booker_city=Amsterdam' \
--data-urlencode 'cc_cardholder=TestFirstName' \
--data-urlencode 'cc_expiration_date=yyyy-mm-dd' \
--data-urlencode 'vc_itemised_charges=taxes,parking,phone,food_beverage' \
--data-urlencode 'vc_itemised_charge_internet=10'
```
**Options when making a booking**
***In-stay service charges***
You can choose to notify the hotel of additional in-stay services that are permitted to be charged to the card. You have 3 options when doing this.
**Option 1:** List specific charges with no amount.
If the traveller can pay for in-stay-charges to the virtual card provided we support informing the hotel as such by printing the additional charges on the authorisation form which is delivered to the hotel. This is done by passing the parameter `vc_itemised_charges`, whose value is a list of one of more of the following:
- `breakfast` for Breakfast
- `food_beverage` for Food and beverage
- `taxes` for Taxes
- `parking` for Parking
- `internet` for Internet
- `phone` for Phone
- `alcohol` for Alcohol
- `no_alcohol` for No alcohol
*Notes:*
- For better clarity, _Dinner_ has been replaced with _Food and beverage_. (NEW)
- When using this feature ensure you have pre-funded the virtual card with enough money to pay for the additional in stay-charges.
**Option 2:** List specific charges with an amount. (NEW)
You can choose to specify the maximum amount which can be charged for each additional in stay service to the virtual card provided. We support informing the hotel as such by printing both the additional charges and the maximum amount which can be charged on the authorisation form which is delivered to the hotel.
The full set of to in-stay charges that can be set with an amount, and the associated parameters, is:
* Breakfast - `vc_itemised_charge_breakfast`
* Food and beverage - `vc_itemised_charge_food_beverage`
* Taxes - `vc_itemised_charge_taxes`
* Parking - `vc_itemised_charge_parking`
* Internet - `vc_itemised_charge_internet`
* Phone - `vc_itemised_charge_phone`
The value of the parameter is the maximum amount which can be charged for the additional in-stay service
*Notes:*
- The charges are always communicated as _per person per night_
- The booker has to specify the price in the hotel's currency.
**Option 3:** Specify if Alcohol may OR may not be charged to the company card (NEW)
*Notes:*
- If you can specify Alcohol can be charged, `Food and beverage` should be included.
- For each charge, you can only use one of option 1 or option 2. Example: you can not use both `vc_itemised_charge_breakfast` and `vc_itemised_charges=breakfast`. Option 3 can be used with both option 1 and option 2.
- If no input is submitted then the assumption is payment is for reservation price only. If you want to pay for additional in-stay services then pass one of the values into the parameter.
***Total Charges***
You can choose to notify the hotel of the total charge that is permitted to be charged to the card. You need to pass the value in hotel currency with parameter **"vc_itemised_charge_total"**
*Notes:*
- The charge is communicated for the entire stay.
- The booker has to specify the price in the hotel's currency.
***Invoice requirements***
You can choose to ask the hotel to email the invoice to an inbox of your choice with the specific requirements you would like to see on the invoice such as the legal entity name, legal entity address, and legal entity VAT number printed on the invoice.
*Notes:*
- You can specify a centralized mailbox for invoices by using "vc_invoice_email". If not specified, an invoice will be sent to the "booker_email" address, or to the first "guest_emails" address if "vc_invoice_to_guest" is true.
***Send authorisation forms to the guest***
To ensure a smoother check-in and check-out process please forward the authorisation form with the one time use virtual card number to the traveler, which they need to display at check-in. To ensure 2 step verification you need to provide both the travelers mobile number ("vc_phones_for_auth_form_pin") and email address ("guest_emails").
***Receive authorisation form in XML response***
You can also choose to deliver the authorisation form to the guest in your own environment. If you would like to receive the authorisation form in XML response as a URL which links to the PDF use the parameter extras and ensure the value is "auth_form_url". (Example: "extras=auth_form_url")
*Notes:*
- The link to a PDF will be returned, and needs to be saved immediately as the link will expire in 7 minutes.
***Contact person at Travel Management Company / Company***
You can choose to print the full name, phone number and email of your chosen contact person should the property have any issues charging the virtual card.