Implementing Payments Clarity Package v2
This topic details the scope of change when implementing the Payments Clarity Package v2 and outlines steps to test, and identify the change in the response.
Understanding the scope of change
If you had implemented the existing Payments Clarity Package feature, following are the possible changes when implementing the new Payments Clarity Package v2:
Change 1: Withheld tax details shown under price details
You can find an additional entry for every tax component that Booking.com has to withhold with the value {{Tax_Name}} (withheld tax) underextracomponent > text.Change 2: Improved payment details: Price details showing collection (guest) and disbursement breakdown (hotel)
You can find two sections in the response schema:guestandhotellisting the booking amount breakup. If you previously used the features: Payments Clarity Package (vcc_payment_v2) or the Include Price Details (include_price_details), the price breakdown data will now be replaced.Change 3: New logic when calculating the total amount for guest view (
guest>total) and hotel view (hotel>total) The total amount is calculated based on the new definition.
Comparing response changes
| Payment solution | Response elements Changed | When using the Payments Clarity Package ( vcc_payment_v2) and/or Include price details (include_price_details) | When using the Payments Clarity Package v2 ( payment_clarity_package_v2) |
|---|---|---|---|
| VCC Bookings Property where Booking.com is obligated to withhold tax | guest > included | Indicates whether the taxes/fees are included in the room price that Booking.com shows to guests. | Indicates whether Booking.com collected the taxes/fees amount from the guest during the booking process. |
guest > total | Indicates the price amount that Booking.com shows to guests. | Indicates the total amount that Booking.com collected from the guests for the booked room. | |
hotel > included | Indicates whether the taxes/fees are included in the room price of the reservation as specified in the Extranet VAT/tax/charges page. | Indicates whether the taxes/fees amount is included in the payout to the property for the booked room. | |
hotel > total | Indicates the price amount of the reservation. | Indicates the total payout amount to the property for the booked room. | |
| VCC balance* | Indicates the amount that the properties can charge on the VCC. | - Bookings with withheld tax: The amount that properties can charge on the VCC. Note that this excludes the withheld tax that Booking.com has withheld and will remit on property's behalf. - Bookings without withheld tax: The amount that properties can charge on the VCC. | |
| Bank transfer bookings Property where Booking.com is obligated to withhold tax | guest > included | Indicates whether the taxes/fees are included in the room price that Booking.com shows to guests. | Indicates whether Booking.com collected the taxes/fees amount from the guest during the booking process for the booked room. |
guest > total | Indicates the price amount that Booking.com shows to guests. | Indicates the total amount that Booking.com collected from the guests for the booked room. | |
hotel > included | Indicates whether the taxes/fees are included in the room price of the reservation as specified in the Extranet VAT/tax/charges page. | Indicates whether the taxes/fees amount is included in the payout to the property for the booked room. | |
hotel > total | Indicates the price amount of the reservation. | Indicates the total payout amount to the property for the booked room. | |
| Agency bookings^ | guest > included | Indicates whether the taxes/fees are included in the room price that Booking.com shows to guests. | Indicates whether the taxes/fees amount is included in the total amount the guest will pay to the property for the booked room. |
guest > total | Indicates the price amount that Booking.com shows to guests. | Indicates the total amount that the guest will pay to the property for the booked room. | |
hotel > included | Indicates whether the taxes/fees are included in the room price of the reservation as specified in the Extranet VAT/tax/charges page. | Indicates whether the taxes/fees amount is included in the total amount that the property should collect from the guest for the booked room. | |
hotel > total | Indicates the price amount of the reservation. | Indicates the total amount the property should collect from the guest. |
^ hotel > total amount is always the same as the guest > total amount.
^ hotel > included value is always the same as the guest > included value.
* Not available when using the Include price details (include_price_details) feature.
Based on the changes discussed above, make sure to:
- Update all properties with the new definition of the included or inclusive/exclusive values of taxes / fees in the price breakdown.
- Revisit the price calculation:
If you validate whether fees, taxes or charges are included in the price when recalculating the reservation price using the Include Price Details (include_price_details) or the Payments Clarity Package (vcc_payment_v2) features, you must update your calculations.
To avoid showing incorrect reservation prices, revisit the price calculation as the relevant flags and amounts will change when the new Payments Clarity Package v2 (payment_clarity_package_v2) feature is enabled.
B.XML response changes
What do the changes mean for properties?
After implementing Payments Clarity Package v2 (payment_clarity_package_v2), properties can determine:
- Whether they need to collect certain taxes / fees from guest.
- Whether they need to remit the taxes / fees to the authorities directly. You can find more information in Summary of different combinations of included value.
Before you start
Make sure you follow these high-level steps to set up a test environment:
Request a test property with withheld tax configured.
i) Contact the Connectivity Support team to request a test property. The test property will have withheld tax and Payments by Booking virtual credit cards (VCCs) solution enabled.
ii) Set availability for the test property with withheld tax and create test reservations:
Follow the tutorial Create a test reservation to set availability and make test reservations.
iii) Set low room inventory prices and a flexible cancellation policy which allows for free cancellation.
iv) While creating test bookings, use a valid payment method, such as using a PayPal account. You will receive a refund upon cancellation.Prepare a test property without withheld tax configured, to see the changes that Payments Clarity Package v2 will bring for properties without withheld tax, such as changes in the confirmation of non-Payments by Booking reservations (agency bookings).
i) Prepare a test property that is not on Payments by Booking.
ii) Follow the tutorial Create a test reservation and use our test credit card (card number 4111 1111 1111 1111) for the payment method.(Optional) Prepare a test property without withheld tax configured and is on Payments by Booking (Bank Transfer), to see the changes that Payments Clarity Package v2 will bring for properties without withheld tax.*
i) Prepare a test property that is on Payments by Booking (Bank Transfer).
ii) Follow the tutorial Create a test reservation and use a valid payment method, such as using a PayPal account. You will receive a refund upon cancellation.
How to test
Make an API request to retrieve an existing reservation using the reservation ID (id) parameter and specify the feature in the header to see and compare the changes.
- Make a request for a reservation using your current implementation.
- Make the same request but add the
Features: payment_clarity_package_v2header. - Compare the responses to understand how your price calculations will need to change.
For example, you can send a cURL request by adding the header as follows:
curl -X GET -H "Authorization: Basic xxXXxx" -H "Features: payment_clarity_package_v2" -H "Cache-Control: no-cache" URLTesting tax withholding component
For providers who manage properties located in a region where Booking.com is obligated to withhold and remit taxes on behalf of the property: Before testing this feature you need to fulfill certain additional requirements. For more information, contact the Connectivity Support team.
Identifying use cases to test
We recommend to test the following use cases to make sure you can deliver the relevant taxes and fees information for your connected properties. You can find more details and how to test it in this session.
| Use cases | Test properties to use | Who needs to test this? | What changes will the Payments Clarity Package v2 bring? |
|---|---|---|---|
| Test reservation with withheld tax and is on Payments by Booking (Virtual Credit Card) | Test property you get from the Connectivity Support Team (with withheld tax configured) | If you work with Payments by Booking (Virtual Credit Card) properties where Booking.com is obligated to withhold taxes | - Additional withheld tax details - New definition for the included values specific to taxes and fees impacting guest view and hotel view^ - New logic when calculating the total amount for guest view and hotel view^ |
| Test reservation without withheld tax and is on Payments by Booking (Virtual Credit Card) | Any test property you have that is on Payments by Booking (Virtual Credit Card) | If you work with Payments by Booking (Virtual Credit Card) properties where Booking.com is not obligated to withhold taxes | - New definition for the included values specific to taxes and fees for guest view and hotel view^ - New logic when calculating the total amount for guest view and hotel view^ |
| Test reservation without withheld tax and is on Payments by Booking (Bank Transfer)* | Any test property you have that is on Payments by Booking (Bank Transfer) | If you work with Payments by Booking (Bank Transfer) properties where Booking.com is not obligated to withhold taxes | - New definition for the included values specific to taxes and fees for guest view and hotel view^ - New logic when calculating the total amount for guest view and hotel view^ |
| Test reservation without withheld tax and is not on Payments by Booking (agency bookings) | Any test property you have that is NOT on Payments by Booking | If you work with properties that are not on Payments by Booking where Booking.com is not obligated to withhold taxes | - New definition for the included values specific to taxes and fees impacting guest view and hotel view^ - New logic when calculating the total amount for guest view and hotel view^ |
^ Only applicable if you’ve implemented the Reservations API with B.XML specification and have been using the feature: Payments Clarity Package (vcc_payment_v2) or Include Price Details (include_price_details)
* Only applicable if you work with properties that are on Payments by Booking (Bank Transfer) and want to see the changes that Payments Clarity Package v2 (payment_clarity_package_v2) will bring for properties without withheld tax.
Test reservation with withheld tax and is on Payments by Booking (Virtual Credit Card)
i) Create a test reservation on the test property (the one with withheld tax configured) you obtained from the Connectivity Support team.
ii) Retrieve reservation messages using feature Payments Clarity Package v2 as described in How to test.
iii) Retrieve the reservation messages again with features you’ve implemented, and without using the feature Payments Clarity Package v2 in the next pull.
iv) Validate the API responses between the responses you got from steps (ii) and (iii).
Test reservation without withheld tax and where the property is on Payments by Booking (Virtual Credit Card)
i) Create a test reservation on any test property on Payments by Booking (Virtual Credit Card) that does not have withheld tax setup.
ii) Retrieve reservation messages using feature Payments Clarity Package v2 as described in How to test.
iii) Retrieve the reservation messages again with features you’ve implemented, and without using the feature Payments Clarity Package v2 in the next pull.
iv) Validate the API responses between the responses you got from steps (ii) and (iii).
Test reservation without withheld tax and where the property is on Payments by Booking (Bank Transfer)
i) Create a test reservation on any test property on Payments by Booking (Bank transfer) and that does not have withheld tax setup.
ii) Retrieve reservation messages using feature Payments Clarity Package v2 as described in How to test.
iii) Retrieve the reservation messages again with features you’ve implemented, and without using the feature Payments Clarity Package v2 in the next pull.
iv) Validate the API responses between the responses you got from steps (ii) and (iii).
Test reservation without withheld tax and where the property is not on Payments by Booking
i) Create a test reservation on any test property not on Payments by Booking and that does not have withheld tax setup.
ii) Retrieve reservation messages using feature Payments Clarity Package v2 as described in How to test.
iii) Retrieve the reservation messages again with features you’ve implemented, and without using the feature Payments Clarity Package v2 in the next pull.
iv) Validate the API responses between the responses you got from steps (ii) and (iii).
B.XML response examples
Following is a summary of response examples covered in this section:
B.XML response with Payments Clarity Package (vcc_payment_v2) | B.XML response with Payments Clarity Package v2 (payment_clarity_package_v2) |
|---|---|
| Current example | Response with withheld tax |
| Multiroom property response example | Multiroom property response with withheld tax |
| Current example | Response without withheld tax |
B.XML response with the existing Payments Clarity Package
For the example responses in this section, the following price configurations are set up for the property:
- The price of the room is $10.
- The price excludes:
- Withheld tax of 2.00%
- Withheld tax of 5.00%
- Withheld tax of 1.50%
- City tax of 5.50%
Also, either the Payments Clarity Package (vcc_payment_v2), or the Include Price Details (include_price_details) feature is turned on.
Expand this section to view the B.XML response example with the existing Payments Clarity Package (vcc_payment_v2) enabled.
<reservations>
<reservation>
<commissionamount>0</commissionamount>
<currencycode>USD</currencycode>
<customer>
<address>********</address>
<cc_activation_date>********</cc_activation_date>
<cc_current_balance>11.45</cc_current_balance>
<cc_cvc>********</cc_cvc>
<cc_expiration_date>********</cc_expiration_date>
<cc_name>********</cc_name>
<cc_number>****************</cc_number>
<cc_type>MasterCard (virtual credit card)</cc_type>
<city></city>
<company></company>
<countrycode>NL</countrycode>
<currencycode>USD</currencycode>
<dc_issue_number></dc_issue_number>
<dc_start_date></dc_start_date>
<email>dennis@guest.booking.com</email>
<first_name>Dennis</first_name>
<last_name>Stanford</last_name>
<remarks>You have received a virtual credit card for this reservation.You may charge it as of 2024-04-24.
</remarks>
<telephone>+31 6 14901111</telephone>
<vcc_expiration_date>2025-04-01</vcc_expiration_date>
<zip></zip>
</customer>
<date>2024-04-05</date>
<hotel_id>11783895</hotel_id>
<hotel_name>PCP Property</hotel_name>
<id>4310937700</id>
<reservation_extra_info>
<flags>
<flag name="booker_is_genius" />
</flags>
<payer>
<payments>
<payment amount="11.45"
currency="USD"
payment_type="payment_on_Booking.com"
payout_type="Virtual credit card" />
</payments>
</payer>
</reservation_extra_info>
<room>
<arrival_date>2024-04-24</arrival_date>
<commissionamount>0</commissionamount>
<currencycode>USD</currencycode>
<departure_date>2024-04-25</departure_date>
<extra_info></extra_info>
<facilities>Internet facilities, Bath, Air conditioning, Hairdryer, Balcony, Desk, Seating Area, Free toiletries, Microwave, Washing machine, Private bathroom, Flat-screen TV, Electric kettle, Kitchenware, Tumble dryer, Bidet, Children's high chair, Game console – PS4, Cots, Shampoo, Body soap</facilities>
<guest_name>Dennis Stanford</guest_name>
<id>1178389503</id>
<info>Breakfast costs US$14 per person per night.
Dinner costs US$35 per person per night. Children and Extra Bed Policy: Children of any age are allowed. 1 child (up to and including 3 years old) stays for US$25 per child per stay when using available cots. 1 person (4 years old and over) stays for US$60 per child per night when using available extra beds. The maximum number of extra beds is 1. The maximum number of cots is 1. The maximum number of guests is 2. Deposit Policy: The guest will be charged a prepayment of the cost of the first night after reservation. Cancellation Policy: The guest can cancel free of charge until 14:00 on the day of arrival. The guest will be charged the cost of the first night if they cancel after 14:00 on the day of arrival. </info>
<max_children>1</max_children>
<meal_plan>Breakfast costs US$14 per person per night.
Dinner costs US$35 per person per night.</meal_plan>
<name>Double Room</name>
<numberofguests>2</numberofguests>
<price date="2024-04-24"
genius_rate="no"
rate_id="43584505"
rewritten_from_id="0"
rewritten_from_name="">10</price>
<price_details>
<guest>
<extracomponent amount="0.55"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="5.5%"
text="City tax" />
<extracomponent amount="0.90"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="8.5%"
text="Tax" />
<total>11.45</total>
</guest>
<hotel>
<extracomponent amount="0.55"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="5.5%"
text="City tax" />
<extracomponent amount="0.90"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="8.5%"
text="Tax" />
<total>10</total>
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>4817804923</roomreservation_id>
<smoking>1</smoking>
<totalprice>10</totalprice>
</room>
<status>new</status>
<time>16:05:59</time>
<totalprice>10</totalprice>
</reservation>
</reservations> B.XML response with the new Payments Clarity Package v2
For the following example, the new Payments Clarity Package v2 (payment_clarity_package_v2) is enabled.
Expand this section to view the B.XML response example with the new Payments Clarity Package v2 (payment_clarity_package_v2) enabled.
The example shows multiple withheld tax components
The following example shows multiple withheld tax components. The number of withheld tax components depends on the local tax regulations and may vary for your implementation.
<reservations>
<reservation>
<commissionamount>0</commissionamount>
<currencycode>USD</currencycode>
<customer>
<address>********</address>
<cc_activation_date>********</cc_activation_date>
<cc_current_balance>10.55</cc_current_balance>
<cc_cvc>********</cc_cvc>
<cc_expiration_date>********</cc_expiration_date>
<cc_name>********</cc_name>
<cc_number>****************</cc_number>
<cc_type>MasterCard (virtual credit card)</cc_type>
<city></city>
<company></company>
<countrycode>NL</countrycode>
<currencycode>USD</currencycode>
<dc_issue_number></dc_issue_number>
<dc_start_date></dc_start_date>
<email>dennis@guest.booking.com</email>
<first_name>Dennis</first_name>
<last_name>Stanford</last_name>
<remarks>You have received a virtual credit card for this reservation.You may charge it as of 2024-04-24.
</remarks>
<telephone>+31 6 14901111</telephone>
<vcc_expiration_date>2025-04-01</vcc_expiration_date>
<zip></zip>
</customer>
<date>2024-04-05</date>
<hotel_id>11783895</hotel_id>
<hotel_name>PCP Property</hotel_name>
<id>4310937700</id>
<reservation_extra_info>
<flags>
<flag name="booker_is_genius" />
</flags>
<payer>
<payments>
<payment amount="10.55"
currency="USD"
payment_type="payment_on_Booking.com"
payout_type="Virtual credit card" />
</payments>
</payer>
</reservation_extra_info>
<room>
<arrival_date>2024-04-24</arrival_date>
<commissionamount>0</commissionamount>
<currencycode>USD</currencycode>
<departure_date>2024-04-25</departure_date>
<extra_info></extra_info>
<facilities>Internet facilities, Bath, Air conditioning, Hairdryer, Balcony, Desk, Seating Area, Free toiletries, Microwave, Washing machine, Private bathroom, Flat-screen TV, Electric kettle, Kitchenware, Tumble dryer, Bidet, Children's high chair, Game console – PS4, Cots, Shampoo, Body soap</facilities>
<guest_name>Dennis Stanford</guest_name>
<id>1178389503</id>
<info>Breakfast costs US$14 per person per night.
Dinner costs US$35 per person per night. Children and Extra Bed Policy: Children of any age are allowed. 1 child (up to and including 3 years old) stays for US$25 per child per stay when using available cots. 1 person (4 years old and over) stays for US$60 per child per night when using available extra beds. The maximum number of extra beds is 1. The maximum number of cots is 1. The maximum number of guests is 2. Deposit Policy: The guest will be charged a prepayment of the cost of the first night after reservation. Cancellation Policy: The guest can cancel free of charge until 14:00 on the day of arrival. The guest will be charged the cost of the first night if they cancel after 14:00 on the day of arrival. </info>
<max_children>1</max_children>
<meal_plan>Breakfast costs US$14 per person per night.
Dinner costs US$35 per person per night.</meal_plan>
<name>Double Room</name>
<numberofguests>2</numberofguests>
<price date="2024-04-24"
genius_rate="no"
rate_id="43584505"
rewritten_from_id="0"
rewritten_from_name="">10</price>
<price_details>
<guest>
<extracomponent amount="0.55"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="5.5%"
text="City tax" />
<extracomponent amount="0.16"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="1.50%"
text="Tax (Withheld Tax)" />
<extracomponent amount="0.21"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="2.00%"
text="Tax (Withheld Tax)" />
<extracomponent amount="0.53"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="5.00%"
text="Tax (Withheld Tax)" /> # Only applicable for properties located in a region where Booking.com is
# obligated to withhold and remit taxes on behalf of the property.
# Can contain as many withheld tax components as the local tax
# regulation stipulates.
<total>11.45</total> # Indicates the amount that Booking.com collected from the guest during booking process
</guest>
<hotel>
<extracomponent amount="0.55"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="5.5%"
text="City tax" />
<extracomponent amount="0.16"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="1.50%"
text="Tax (Withheld Tax)" />
<extracomponent amount="0.21"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="2.00%"
text="Tax (Withheld Tax)" />
<extracomponent amount="0.53"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="5.00%"
text="Tax (Withheld Tax)" /> # Only applicable for properties located in a region where Booking.com is
# obligated to withhold and remit taxes on behalf of the property.
# Can contain as many withheld tax components as the local tax
# regulation stipulates.
<total>10.55</total> # Indicates the total payout amount to the property
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>4817804923</roomreservation_id>
<smoking>1</smoking>
<totalprice>10</totalprice>
</room>
<status>new</status>
<time>16:05:59</time>
<totalprice>10</totalprice>
</reservation>
</reservations> B.XML response for multiroom property using existing Payments Clarity Package
For the following response examples the following price configurations are set up for the property:
- The price of the room is $10.
- The price excludes:
- Withheld tax of 8.50%
- City tax of 5.50%
Also, either the Payments Clarity Package (vcc_payment_v2), or the Include Price Details (include_price_details) feature is turned on.
Expand this section to view the B.XML response example with the existing Payments Clarity Package (vcc_payment_v2) enabled.
<reservations>
<reservation>
<commissionamount>0</commissionamount>
<currencycode>USD</currencycode>
<customer>
<address>********</address>
<cc_activation_date>********</cc_activation_date>
<cc_current_balance>22.90</cc_current_balance>
<cc_cvc>********</cc_cvc>
<cc_expiration_date>********</cc_expiration_date>
<cc_name>Bookingcom Agent</cc_name>
<cc_number>****************</cc_number>
<cc_type>MasterCard (virtual credit card)</cc_type>
<city></city>
<company></company>
<countrycode>NL</countrycode>
<currencycode>USD</currencycode>
<dc_issue_number></dc_issue_number>
<dc_start_date></dc_start_date>
<email>lucy@guest.booking.com</email>
<first_name>Lucy</first_name>
<last_name>Taylor</last_name>
<remarks>You have received a virtual credit card for this reservation.You may charge it as of 2024-03-30.
</remarks>
<telephone>+31 6 14901111</telephone>
<vcc_expiration_date>2025-03-01</vcc_expiration_date>
<zip></zip>
</customer>
<date>2024-03-28</date>
<hotel_id>11761142</hotel_id>
<hotel_name>PCP Property</hotel_name>
<id>4787168583</id>
<reservation_extra_info>
<flags>
<flag name="booker_is_genius" />
</flags>
<payer>
<payments>
<payment amount="22.90"
currency="USD"
payment_type="payment_on_Booking.com"
payout_type="Virtual credit card" />
</payments>
</payer>
</reservation_extra_info>
<room>
<arrival_date>2024-03-30</arrival_date>
<commissionamount>0</commissionamount>
<currencycode>USD</currencycode>
<departure_date>2024-03-31</departure_date>
<extra_info></extra_info>
<facilities>Internet facilities, Bath, Air conditioning, Hairdryer, Balcony, Desk, Seating Area, Free toiletries, Microwave, Washing machine, Private bathroom, Flat-screen TV, Electric kettle, Kitchenware, Tumble dryer, Bidet, Children's high chair, Game console – PS4, Cots, Shampoo, Body soap</facilities>
<guest_name>Lucy Taylor</guest_name>
<id>1176114203</id>
<info>Breakfast costs US$14 per person per night.
Dinner costs US$35 per person per night. Children and Extra Bed Policy: Children of any age are allowed. 1 child (up to and including 3 years old) stays for US$25 per child per stay when using available cots. 1 person (4 years old and over) stays for US$60 per child per night when using available extra beds. The maximum number of extra beds is 1. The maximum number of cots is 1. The maximum number of guests is 2. Deposit Policy: The guest will be charged a prepayment of the cost of the first night after reservation. Cancellation Policy: The guest can cancel free of charge until 18:00 on the day of arrival. The guest will be charged the cost of the first night if they cancel after 18:00 on the day of arrival. </info>
<max_children>1</max_children>
<meal_plan>Breakfast costs US$14 per person per night.
Dinner costs US$35 per person per night.</meal_plan>
<name>Double Room</name>
<numberofguests>1</numberofguests>
<price date="2024-03-30"
genius_rate="no"
rate_id="43470373"
rewritten_from_id="0"
rewritten_from_name="">10</price>
<price_details>
<guest>
<extracomponent amount="0.55"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="5.5%"
text="City tax" />
<extracomponent amount="0.90"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="8.5%"
text="Tax" />
<total>11.45</total>
</guest>
<hotel>
<extracomponent amount="0.55"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="5.5%"
text="City tax" />
<extracomponent amount="0.90"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="8.5%"
text="Tax" />
<total>10</total>
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>4803678746</roomreservation_id>
<smoking>1</smoking>
<totalprice>10</totalprice>
</room>
<room>
<arrival_date>2024-03-30</arrival_date>
<commissionamount>0</commissionamount>
<currencycode>USD</currencycode>
<departure_date>2024-03-31</departure_date>
<extra_info></extra_info>
<facilities>Internet facilities, Bath, Air conditioning, Hairdryer, Balcony, Desk, Seating Area, Free toiletries, Microwave, Washing machine, Private bathroom, Flat-screen TV, Electric kettle, Kitchenware, Tumble dryer, Bidet, Children's high chair, Game console – PS4, Cots, Shampoo, Body soap</facilities>
<guest_name>Lucy Taylor</guest_name>
<id>1176114203</id>
<info>Breakfast costs US$14 per person per night.
Dinner costs US$35 per person per night. Children and Extra Bed Policy: Children of any age are allowed. 1 child (up to and including 3 years old) stays for US$25 per child per stay when using available cots. 1 person (4 years old and over) stays for US$60 per child per night when using available extra beds. The maximum number of extra beds is 1. The maximum number of cots is 1. The maximum number of guests is 2. Deposit Policy: The guest will be charged a prepayment of the cost of the first night after reservation. Cancellation Policy: The guest can cancel free of charge until 18:00 on the day of arrival. The guest will be charged the cost of the first night if they cancel after 18:00 on the day of arrival. </info>
<max_children>1</max_children>
<meal_plan>Breakfast costs US$14 per person per night.
Dinner costs US$35 per person per night.</meal_plan>
<name>Double Room</name>
<numberofguests>1</numberofguests>
<price date="2024-03-30"
genius_rate="no"
rate_id="43470373"
rewritten_from_id="0"
rewritten_from_name="">10</price>
<price_details>
<guest>
<extracomponent amount="0.55"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="5.5%"
text="City tax" />
<extracomponent amount="0.90"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="8.5%"
text="Tax" />
<total>11.45</total>
</guest>
<hotel>
<extracomponent amount="0.55"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="5.5%"
text="City tax" />
<extracomponent amount="0.90"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="8.5%"
text="Tax" />
<total>10</total>
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>4803678762</roomreservation_id>
<smoking>1</smoking>
<totalprice>10</totalprice>
</room>
<status>new</status>
<time>15:24:22</time>
<totalprice>20</totalprice>
</reservation>
</reservations>
B.XML response for multiroom property with the new Payments Clarity Package v2 feature
Expand this section to view the B.XML response example with the new Payments Clarity Package v2 (payment_clarity_package_v2) enabled.
<reservations>
<reservation>
<commissionamount>0</commissionamount>
<currencycode>USD</currencycode>
<customer>
<address>********</address>
<cc_activation_date>********</cc_activation_date>
<cc_current_balance>21.10</cc_current_balance>
<cc_cvc>********</cc_cvc>
<cc_expiration_date>********</cc_expiration_date>
<cc_name>Bookingcom Agent</cc_name>
<cc_number>****************</cc_number>
<cc_type>MasterCard (virtual credit card)</cc_type>
<city>********</city>
<company>********</company>
<countrycode>NL</countrycode>
<currencycode>USD</currencycode>
<dc_issue_number></dc_issue_number>
<dc_start_date></dc_start_date>
<email>lucy@guest.booking.com</email>
<first_name>Lucy</first_name>
<last_name>Taylor</last_name>
<remarks>You have received a virtual credit card for this reservation.You may charge it as of 2024-03-30.
</remarks>
<telephone>+31 6 14901111</telephone>
<vcc_expiration_date>2025-03-01</vcc_expiration_date>
<zip></zip>
</customer>
<date>2024-03-28</date>
<hotel_id>11761142</hotel_id>
<hotel_name>PCP Property</hotel_name>
<id>4787168583</id>
<reservation_extra_info>
<flags>
<flag name="booker_is_genius" />
</flags>
<payer>
<payments>
<payment amount="21.10"
currency="USD"
payment_type="payment_on_Booking.com"
payout_type="Virtual credit card" />
</payments>
</payer>
</reservation_extra_info>
<room>
<arrival_date>2024-03-30</arrival_date>
<commissionamount>0</commissionamount>
<currencycode>USD</currencycode>
<departure_date>2024-03-31</departure_date>
<extra_info></extra_info>
<facilities>Internet facilities, Bath, Air conditioning, Hairdryer, Balcony, Desk, Seating Area, Free toiletries, Microwave, Washing machine, Private bathroom, Flat-screen TV, Electric kettle, Kitchenware, Tumble dryer, Bidet, Children's high chair, Game console – PS4, Cots, Shampoo, Body soap</facilities>
<guest_name>Lucy Taylor</guest_name>
<id>1176114203</id>
<info>Breakfast costs US$14 per person per night.
Dinner costs US$35 per person per night. Children and Extra Bed Policy: Children of any age are allowed. 1 child (up to and including 3 years old) stays for US$25 per child per stay when using available cots. 1 person (4 years old and over) stays for US$60 per child per night when using available extra beds. The maximum number of extra beds is 1. The maximum number of cots is 1. The maximum number of guests is 2. Deposit Policy: The guest will be charged a prepayment of the cost of the first night after reservation. Cancellation Policy: The guest can cancel free of charge until 18:00 on the day of arrival. The guest will be charged the cost of the first night if they cancel after 18:00 on the day of arrival. </info>
<max_children>1</max_children>
<meal_plan>Breakfast costs US$14 per person per night.
Dinner costs US$35 per person per night.</meal_plan>
<name>Double Room</name>
<numberofguests>1</numberofguests>
<price date="2024-03-30"
genius_rate="no"
rate_id="43470373"
rewritten_from_id="0"
rewritten_from_name="">10</price>
<price_details>
<guest>
<extracomponent amount="0.55"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="5.5%"
text="City tax" />
<extracomponent amount="0.90"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="8.50%"
text="Tax (Withheld Tax)" /> # Only applicable for properties located in a region where Booking.com is
# obligated to withhold and remit taxes on behalf of the property.
# Can contain as many withheld tax components as the local tax
# regulation stipulates.
<total>11.45</total> # Indicates the amount that Booking.com collected from the guest during booking process
</guest>
<hotel>
<extracomponent amount="0.55"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="5.5%"
text="City tax" />
<extracomponent amount="0.90"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="8.50%"
text="Tax (Withheld Tax)" /> # Only applicable for properties located in a region where Booking.com is
# obligated to withhold and remit taxes on behalf of the property.
# Can contain as many withheld tax components as the local tax
# regulation stipulates.
<total>10.55</total> # Indicates the total payout amount to the property
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>4803678746</roomreservation_id>
<smoking>1</smoking>
<totalprice>10</totalprice>
</room>
<room>
<arrival_date>2024-03-30</arrival_date>
<commissionamount>0</commissionamount>
<currencycode>USD</currencycode>
<departure_date>2024-03-31</departure_date>
<extra_info></extra_info>
<facilities>Internet facilities, Bath, Air conditioning, Hairdryer, Balcony, Desk, Seating Area, Free toiletries, Microwave, Washing machine, Private bathroom, Flat-screen TV, Electric kettle, Kitchenware, Tumble dryer, Bidet, Children's high chair, Game console – PS4, Cots, Shampoo, Body soap</facilities>
<guest_name>Lucy Taylor</guest_name>
<id>1176114203</id>
<info>Breakfast costs US$14 per person per night.
Dinner costs US$35 per person per night. Children and Extra Bed Policy: Children of any age are allowed. 1 child (up to and including 3 years old) stays for US$25 per child per stay when using available cots. 1 person (4 years old and over) stays for US$60 per child per night when using available extra beds. The maximum number of extra beds is 1. The maximum number of cots is 1. The maximum number of guests is 2. Deposit Policy: The guest will be charged a prepayment of the cost of the first night after reservation. Cancellation Policy: The guest can cancel free of charge until 18:00 on the day of arrival. The guest will be charged the cost of the first night if they cancel after 18:00 on the day of arrival. </info>
<max_children>1</max_children>
<meal_plan>Breakfast costs US$14 per person per night.
Dinner costs US$35 per person per night.</meal_plan>
<name>Double Room</name>
<numberofguests>1</numberofguests>
<price date="2024-03-30"
genius_rate="no"
rate_id="43470373"
rewritten_from_id="0"
rewritten_from_name="">10</price>
<price_details>
<guest>
<extracomponent amount="0.55"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="5.5%"
text="City tax" />
<extracomponent amount="0.90"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="8.50%"
text="Tax (Withheld Tax)" /> # Only applicable for properties located in a region where Booking.com is
# obligated to withhold and remit taxes on behalf of the property.
# Can contain as many withheld tax components as the local tax
# regulation stipulates.
<total>11.45</total> # Indicates the amount that Booking.com collected from the guest during booking process
</guest>
<hotel>
<extracomponent amount="0.55"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="5.5%"
text="City tax" />
<extracomponent amount="0.90"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="8.50%"
text="Tax (Withheld Tax)" /> # Only applicable for properties located in a region where Booking.com is
# obligated to withhold and remit taxes on behalf of the property.
# Can contain as many withheld tax components as the local tax
# regulation stipulates.
<total>10.55</total> # Indicates the total payout amount to the property
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>4803678762</roomreservation_id>
<smoking>1</smoking>
<totalprice>10</totalprice>
</room>
<status>new</status>
<time>15:24:22</time>
<totalprice>20</totalprice>
</reservation>
</reservations>
B.XML response using existing Payments Clarity Package with no withheld tax component
For the following reservation response examples, the property has the following set up with the existing Payments Clarity Package (vcc_payment_v2) enabled:
- Room Price is €10 per night
- VAT of 18.00% is included
- City tax of 3.50% isn't included
- Bed linens fee of €5 per stay isn't included
Expand this section to view the B.XML response example with the existing Payments Clarity Package (vcc_payment_v2) enabled.
<reservations>
<reservation>
<booked_at>2024-03-25T16:05:26+00:00</booked_at>
<commissionamount>0</commissionamount>
<currencycode>EUR</currencycode>
<customer>
<address>********</address>
<cc_activation_date>********</cc_activation_date>
<cc_current_balance>15.30</cc_current_balance>
<cc_cvc>********</cc_cvc>
<cc_expiration_date>********</cc_expiration_date>
<cc_name>Bookingcom Agent</cc_name>
<cc_number>****************</cc_number>
<cc_type>MasterCard (virtual credit card)</cc_type>
<city>********</city>
<company>********</company>
<countrycode>GB</countrycode>
<currencycode>EUR</currencycode>
<dc_issue_number></dc_issue_number>
<dc_start_date></dc_start_date>
<email>marcus@guest.booking.com</email>
<first_name>Marcus</first_name>
<last_name>Aurelius</last_name>
<remarks>You have received a virtual credit card for this reservation.You may charge it as of 2024-03-28.
</remarks>
<telephone></telephone>
<vcc_expiration_date>2025-03-01</vcc_expiration_date>
<zip></zip>
</customer>
<date>2024-03-25</date>
<guest_counts>
<guest_count count="2"
type="adult" />
</guest_counts>
<hotel_id>10703075</hotel_id>
<hotel_name>Test Hotel</hotel_name>
<id>4609387145</id>
<modified_at>2024-03-25T16:05:27+00:00</modified_at>
<reservation_extra_info>
<flags>
<flag name="booker_is_genius" />
</flags>
<payer>
<payments>
<payment amount="15.30"
currency="EUR"
payment_type="payment_on_Booking.com"
payout_type="Virtual credit card" />
</payments>
</payer>
</reservation_extra_info>
<room>
<arrival_date>2024-03-27</arrival_date>
<cancel_penalties>
<cancel_penalty from="2024-03-25T16:05:26+00:00"
policy_code="38"
until="2024-03-25T23:00:00+00:00">
<amount_percent amount="0"
currency_code="EUR" />
</cancel_penalty>
<cancel_penalty from="2024-03-25T23:00:00+00:00"
policy_code="38">
<amount_percent amount="10"
currency_code="EUR" />
</cancel_penalty>
</cancel_penalties>
<commissionamount>0</commissionamount>
<currencycode>EUR</currencycode>
<departure_date>2024-03-28</departure_date>
<extra_info></extra_info>
<facilities></facilities>
<guest_name>Marcus Aurelius</guest_name>
<id>1070307502</id>
<info>Breakfast costs EUR 14 per person per night.
Dinner costs EUR 35 per person per night. Children and Extra Bed Policy: Children of any age are allowed. You haven't added any cots. You haven't added any extra beds. The maximum number of guests is 2. Deposit Policy: The guest will be charged a prepayment of the total price of the reservation within 1 day before arrival. Cancellation Policy: The guest can cancel free of charge until 1 day before arrival. The guest will be charged the total price of the reservation if they cancel within 1 day before arrival. </info>
<max_children>0</max_children>
<meal_plan>Breakfast costs EUR 14 per person per night.
Dinner costs EUR 35 per person per night.</meal_plan>
<name>Deluxe Double Room with Mountain View</name>
<numberofguests>2</numberofguests>
<occupancy>2</occupancy>
<price date="2024-03-27"
genius_rate="no"
rate_id="38452247"
rewritten_from_id="0"
rewritten_from_name="">10</price>
<price_details>
<guest>
<extracomponent amount="5"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="1.53"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="0.30"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="3.5%"
text="City tax" />
<total>15.30</total>
</guest>
<hotel>
<extracomponent amount="5"
currency="EUR"
included="no"
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="1.53"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="0.30"
currency="EUR"
included="no"
per_night="no"
per_person="no"
percentage="3.5%"
text="City tax" />
<total>10</total>
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>4798390515</roomreservation_id>
<smoking>0</smoking>
<totalprice>10</totalprice>
</room>
<status>new</status>
<time>17:05:26</time>
<totalprice>10</totalprice>
</reservation>
</reservations>B.XML response using the new Payments Clarity Package v2 feature with no withheld tax component
For the following response example, the property has the new Payments Clarity Package v2 (payment_clarity_package_v2) enabled:
Expand this section to view the B.XML response example with the new Payments Clarity Package v2 (payment_clarity_package_v2) enabled.
<reservations>
<reservation>
<booked_at>2024-03-25T16:05:26+00:00</booked_at>
<commissionamount>0</commissionamount>
<currencycode>EUR</currencycode>
<customer>
<address></address>
<cc_activation_date>**********</cc_activation_date>
<cc_current_balance>15.30</cc_current_balance>
<cc_cvc>********</cc_cvc>
<cc_expiration_date>*******</cc_expiration_date>
<cc_name>Bookingcom Agent</cc_name>
<cc_number>****************</cc_number>
<cc_type>MasterCard (virtual credit card)</cc_type>
<city></city>
<company></company>
<countrycode>GB</countrycode>
<currencycode>EUR</currencycode>
<dc_issue_number></dc_issue_number>
<dc_start_date></dc_start_date>
<email>marcus@guest.booking.com</email>
<first_name>Marcus</first_name>
<last_name>Aurelius</last_name>
<remarks>You have received a virtual credit card for this reservation.You may charge it as of 2024-03-28.
</remarks>
<telephone></telephone>
<vcc_expiration_date>2025-03-01</vcc_expiration_date>
<zip></zip>
</customer>
<date>2024-03-25</date>
<guest_counts>
<guest_count count="2"
type="adult" />
</guest_counts>
<hotel_id>10703075</hotel_id>
<hotel_name>Test Hotel</hotel_name>
<id>4609387145</id>
<modified_at>2024-03-25T16:05:27+00:00</modified_at>
<reservation_extra_info>
<flags>
<flag name="booker_is_genius" />
</flags>
<payer>
<payments>
<payment amount="15.30"
currency="EUR"
payment_type="payment_on_Booking.com"
payout_type="Virtual credit card" />
</payments>
</payer>
</reservation_extra_info>
<room>
<arrival_date>2024-03-27</arrival_date>
<cancel_penalties>
<cancel_penalty from="2024-03-25T16:05:26+00:00"
policy_code="38"
until="2024-03-25T23:00:00+00:00">
<amount_percent amount="0"
currency_code="EUR" />
</cancel_penalty>
<cancel_penalty from="2024-03-25T23:00:00+00:00"
policy_code="38">
<amount_percent amount="10"
currency_code="EUR" />
</cancel_penalty>
</cancel_penalties>
<commissionamount>0</commissionamount>
<currencycode>EUR</currencycode>
<departure_date>2024-03-28</departure_date>
<extra_info></extra_info>
<facilities></facilities>
<guest_name>Marcus Aurelius</guest_name>
<id>1070307502</id>
<info>Breakfast costs EUR 14 per person per night.
Dinner costs EUR 35 per person per night. Children and Extra Bed Policy: Children of any age are allowed. You haven't added any cots. You haven't added any extra beds. The maximum number of guests is 2. Deposit Policy: The guest will be charged a prepayment of the total price of the reservation within 1 day before arrival. Cancellation Policy: The guest can cancel free of charge until 1 day before arrival. The guest will be charged the total price of the reservation if they cancel within 1 day before arrival. </info>
<max_children>0</max_children>
<meal_plan>Breakfast costs EUR 14 per person per night.
Dinner costs EUR 35 per person per night.</meal_plan>
<name>Deluxe Double Room with Mountain View</name>
<numberofguests>2</numberofguests>
<occupancy>2</occupancy>
<price date="2024-03-27"
genius_rate="no"
rate_id="38452247"
rewritten_from_id="0"
rewritten_from_name="">10</price>
<price_details>
<guest>
<extracomponent amount="5"
currency="EUR"
included="yes" # Indicates fees/tax was collected from the guest during booking
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="1.53"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="0.30"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="3.5%"
text="City tax" />
<total>15.30</total> # Indicates the amount Booking.com collected from the guest during booking process
</guest>
<hotel>
<extracomponent amount="5"
currency="EUR"
included="yes" # Indicates fees/tax is included in the payout to the property
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="1.53"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="0.30"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="3.5%"
text="City tax" />
<total>15.30</total> # Indicates the total payout amount to the property
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>4798390515</roomreservation_id>
<smoking>0</smoking>
<totalprice>10</totalprice>
</room>
<status>new</status>
<time>17:05:26</time>
<totalprice>10</totalprice>
</reservation>
</reservations> Property on Payments by Booking using Bank transfer as payout
This section shows the Payments Clarity Package (vcc_payment_v2) feature and with the new Payments Clarity Package v2 (payment_clarity_package_v2) feature enabled to help you compare the difference in behaviour.
This section contains response examples based on the Bank transfer payment solution and with/without withheld tax in the response.
Expand to see relevant response examples
As we have included multiple response examples, to improve readability we have collapsed all examples. You can expand to see the examples of specific scenarios that you are interested in.
B.XML response on Bank transfer using the existing Payments Clarity Package feature with no withheld tax component
For the following response example, the property has the existing Payments Clarity Package (vcc_payment_v2) enabled with the following configuration:
- Room Price is €10 per night
- VAT of 18.00% is included
- City tax of 3.50% isn't included
- Bed linens fee of €5 per stay isn't included
Expand this section to view the B.XML response example with the existing Payments Clarity Package (vcc_payment_v2) enabled.
<reservations>
<reservation>
<commissionamount>0</commissionamount>
<currencycode>EUR</currencycode>
<customer>
<address></address>
<cc_current_balance>15.30</cc_current_balance>
<cc_cvc></cc_cvc>
<cc_expiration_date></cc_expiration_date>
<cc_name></cc_name>
<cc_number></cc_number>
<cc_type></cc_type>
<city></city>
<company></company>
<countrycode>NL</countrycode>
<currencycode>EUR</currencycode>
<dc_issue_number></dc_issue_number>
<dc_start_date></dc_start_date>
<email>john@guest.booking.com</email>
<first_name>John</first_name>
<last_name>Doe</last_name>
<remarks>** THIS RESERVATION HAS BEEN PRE-PAID **
BOOKING NOTE : Payment charge is EUR 0.19885593220339</remarks>
<telephone>+31 6 14901111</telephone>
<zip></zip>
</customer>
<date>2024-04-02</date>
<hotel_id>8407009</hotel_id>
<hotel_name>Test Hotel</hotel_name>
<id>4707766190</id>
<reservation_extra_info>
<flags>
<flag name="booker_is_genius" />
</flags>
<payer>
<payments>
<payment amount="15.30"
currency="EUR"
payment_type="payment_on_Booking.com"
payout_type="BankTransfer" />
</payments>
</payer>
</reservation_extra_info>
<room>
<arrival_date>2024-04-26</arrival_date>
<commissionamount>0</commissionamount>
<currencycode>EUR</currencycode>
<departure_date>2024-04-27</departure_date>
<extra_info>The unit offers 1 bed.</extra_info>
<facilities>Private bathroom</facilities>
<guest_name>John Doe</guest_name>
<id>840700903</id>
<info>Breakfast costs EUR 14 per person per night. Children and Extra Bed Policy: Children of any age are allowed. You haven't added any cots. You haven't added any extra beds. The maximum number of guests is 6. Deposit Policy: The guest will be charged a prepayment of the total price of the reservation at any time. Cancellation Policy: The guest can cancel free of charge until 5 days before arrival. The guest will be charged the total price of the reservation if they cancel in the 5 days before arrival. </info>
<max_children>0</max_children>
<meal_plan>Breakfast costs EUR 14 per person per night.</meal_plan>
<name>Apartment</name>
<numberofguests>2</numberofguests>
<price date="2024-04-26"
genius_rate="no"
rate_id="26551143"
rewritten_from_id="0"
rewritten_from_name="">10</price>
<price_details>
<guest>
<extracomponent amount="5"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="1.53"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="0.30"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="3.5%"
text="City tax" />
<total>15.30</total>
</guest>
<hotel>
<extracomponent amount="5"
currency="EUR"
included="no"
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="1.53"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="0.30"
currency="EUR"
included="no"
per_night="no"
per_person="no"
percentage="3.5%"
text="City tax" />
<total>10</total>
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>4812158094</roomreservation_id>
<smoking>0</smoking>
<totalprice>10</totalprice>
</room>
<status>new</status>
<time>16:35:19</time>
<totalprice>10</totalprice>
</reservation>
</reservations>B.XML response on Bank transfer using the new Payments Clarity Package v2 feature with no withheld tax component
For the following response example, the property has the new Payments Clarity Package v2 (payment_clarity_package_v2) enabled with the following configuration:
- Room Price is €10 per night
- VAT of 18.00% is included
- City tax of 3.50% isn't included
- Bed linens fee of €5 per stay isn't included
Expand this section to view the B.XML response example with the new Payments Clarity Package v2 (payment_clarity_package_v2) enabled.
<reservations>
<reservation>
<commissionamount>0</commissionamount>
<currencycode>EUR</currencycode>
<customer>
<address></address>
<cc_current_balance>15.30</cc_current_balance>
<cc_cvc></cc_cvc>
<cc_expiration_date></cc_expiration_date>
<cc_name></cc_name>
<cc_number></cc_number>
<cc_type></cc_type>
<city></city>
<company></company>
<countrycode>NL</countrycode>
<currencycode>EUR</currencycode>
<dc_issue_number></dc_issue_number>
<dc_start_date></dc_start_date>
<email>john@guest.booking.com</email>
<first_name>John</first_name>
<last_name>Doe</last_name>
<remarks>** THIS RESERVATION HAS BEEN PRE-PAID **
BOOKING NOTE : Payment charge is EUR 0.19885593220339</remarks>
<telephone>+31 6 14901111</telephone>
<zip></zip>
</customer>
<date>2024-04-02</date>
<hotel_id>8407009</hotel_id>
<hotel_name>Test Hotel</hotel_name>
<id>4707766190</id>
<reservation_extra_info>
<flags>
<flag name="booker_is_genius" />
</flags>
<payer>
<payments>
<payment amount="15.30"
currency="EUR"
payment_type="payment_on_Booking.com"
payout_type="BankTransfer" />
</payments>
</payer>
</reservation_extra_info>
<room>
<arrival_date>2024-04-26</arrival_date>
<commissionamount>0</commissionamount>
<currencycode>EUR</currencycode>
<departure_date>2024-04-27</departure_date>
<extra_info>The unit offers 1 bed.</extra_info>
<facilities>Private bathroom</facilities>
<guest_name>John Doe</guest_name>
<id>840700903</id>
<info>Breakfast costs EUR 14 per person per night. Children and Extra Bed Policy: Children of any age are allowed. You haven't added any cots. You haven't added any extra beds. The maximum number of guests is 6. Deposit Policy: The guest will be charged a prepayment of the total price of the reservation at any time. Cancellation Policy: The guest can cancel free of charge until 5 days before arrival. The guest will be charged the total price of the reservation if they cancel in the 5 days before arrival. </info>
<max_children>0</max_children>
<meal_plan>Breakfast costs EUR 14 per person per night.</meal_plan>
<name>Apartment</name>
<numberofguests>2</numberofguests>
<price date="2024-04-26"
genius_rate="no"
rate_id="26551143"
rewritten_from_id="0"
rewritten_from_name="">10</price>
<price_details>
<guest>
<extracomponent amount="5"
currency="EUR"
included="yes" # Indicates fees/tax was collected from the guest during booking
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="1.53"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="0.30"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="3.5%"
text="City tax" />
<total>15.30</total> # Indicates the amount Booking.com collected from the guest during booking process
</guest>
<hotel>
<extracomponent amount="5"
currency="EUR"
included="yes" # Indicates fees/tax is included in the payout to the property
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="1.53"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="0.30"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="3.5%"
text="City tax" />
<total>15.30</total> # Indicates the total payout amount to the property
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>4812158094</roomreservation_id>
<smoking>0</smoking>
<totalprice>10</totalprice>
</room>
<status>new</status>
<time>16:35:19</time>
<totalprice>10</totalprice>
</reservation>
</reservations> Agency booking response examples
The following response examples list the B.XML response for agency booking using both the existing and the new Payments Clarity Package v2 features.
Agency booking B.XML response using the existing Payments Clarity Package feature
For the following response example, the property has the existing Payments Clarity Package (vcc_payment_v2) enabled with the following configuration:
- Room Price is €10 per night
- VAT of 5.00% is included
- City tax of 2.50% isn't included
Expand this section to view the B.XML response example with the existing Payments Clarity Package (vcc_payment_v2) enabled.
<reservations>
<reservation>
<commissionamount>0</commissionamount>
<currencycode>EUR</currencycode>
<customer>
<address></address>
<cc_cvc>********</cc_cvc>
<cc_expiration_date>********</cc_expiration_date>
<cc_name>Jennifer Oman</cc_name>
<cc_number>********</cc_number>
<cc_type>Visa</cc_type>
<city></city>
<company></company>
<countrycode>NL</countrycode>
<dc_issue_number></dc_issue_number>
<dc_start_date></dc_start_date>
<email>jennifer@guest.booking.com</email>
<first_name>Jennifer</first_name>
<last_name>Oman</last_name>
<remarks></remarks>
<telephone>+31 6 14901111</telephone>
<zip></zip>
</customer>
<date>2024-04-02</date>
<hotel_id>4889129</hotel_id>
<hotel_name>Test Hotel</hotel_name>
<id>4476717092</id>
<reservation_extra_info>
<flags>
<flag name="booker_is_genius" />
</flags>
</reservation_extra_info>
<room>
<arrival_date>2024-04-07</arrival_date>
<commissionamount>0</commissionamount>
<currencycode>EUR</currencycode>
<departure_date>2024-04-08</departure_date>
<extra_info></extra_info>
<facilities></facilities>
<guest_name>Jennifer Oman</guest_name>
<id>488912902</id>
<info>Full board is included in the room rate. Children and Extra Bed Policy: Children of any age are allowed. You haven't added any cots. You haven't added any extra beds. The maximum number of guests is 0. Deposit Policy: No prepayment is needed. Cancellation Policy: The guest can cancel free of charge until 14:00 on the day of arrival. The guest will be charged the cost of the first night if they cancel after 14:00 on the day of arrival. </info>
<max_children>0</max_children>
<meal_plan>Full board is included in the room rate.</meal_plan>
<name>Double Room</name>
<numberofguests>2</numberofguests>
<price date="2024-04-07"
genius_rate="no"
rate_id="20766042"
rewritten_from_id="0"
rewritten_from_name="">10</price>
<price_details>
<guest>
<extracomponent amount="0.48"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="5%"
text="VAT" />
<extracomponent amount="0.24"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="2.5%"
text="City tax" />
<total>10.24</total>
</guest>
<hotel>
<extracomponent amount="0.48"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="5%"
text="VAT" />
<extracomponent amount="0.24"
currency="EUR"
included="no"
per_night="no"
per_person="no"
percentage="2.5%"
text="City tax" />
<total>10</total>
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>4812008729</roomreservation_id>
<smoking>0</smoking>
<totalprice>10</totalprice>
</room>
<status>new</status>
<time>15:12:44</time>
<totalprice>10</totalprice>
</reservation>
</reservations> Agency booking B.XML response using the new Payments Clarity Package v2 feature
For the following response example, the property has the new Payments Clarity Package v2 (payment_clarity_package_v2) enabled with the following configuration:
- Room Price is €10 per night
- VAT of 5.00% is included
- City tax of 2.50% isn't included
Expand this section to view the B.XML response example with the new Payments Clarity Package v2 (payment_clarity_package_v2) enabled.
<reservations>
<reservation>
<commissionamount>0</commissionamount>
<currencycode>EUR</currencycode>
<customer>
<address></address>
<cc_cvc>********</cc_cvc>
<cc_expiration_date>********</cc_expiration_date>
<cc_name>********</cc_name>
<cc_number>********</cc_number>
<cc_type>Visa</cc_type>
<city></city>
<company></company>
<countrycode>NL</countrycode>
<dc_issue_number></dc_issue_number>
<dc_start_date></dc_start_date>
<email>jennifer@guest.booking.com</email>
<first_name>Jennifer</first_name>
<last_name>Oman</last_name>
<remarks></remarks>
<telephone>+31 6 14901111</telephone>
<zip></zip>
</customer>
<date>2024-04-02</date>
<hotel_id>4889129</hotel_id>
<hotel_name>Test Hotel</hotel_name>
<id>4476717092</id>
<reservation_extra_info>
<flags>
<flag name="booker_is_genius" />
</flags>
</reservation_extra_info>
<room>
<arrival_date>2024-04-07</arrival_date>
<commissionamount>0</commissionamount>
<currencycode>EUR</currencycode>
<departure_date>2024-04-08</departure_date>
<extra_info></extra_info>
<facilities></facilities>
<guest_name>Jennifer Oman</guest_name>
<id>488912902</id>
<info>Full board is included in the room rate. Children and Extra Bed Policy: Children of any age are allowed. You haven't added any cots. You haven't added any extra beds. The maximum number of guests is 0. Deposit Policy: No prepayment is needed. Cancellation Policy: The guest can cancel free of charge until 14:00 on the day of arrival. The guest will be charged the cost of the first night if they cancel after 14:00 on the day of arrival. </info>
<max_children>0</max_children>
<meal_plan>Full board is included in the room rate.</meal_plan>
<name>Double Room</name>
<numberofguests>2</numberofguests>
<price date="2024-04-07"
genius_rate="no"
rate_id="20766042"
rewritten_from_id="0"
rewritten_from_name="">10</price>
<price_details>
<guest>
<extracomponent amount="0.48"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="5%"
text="VAT" />
<extracomponent amount="0.24"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="2.5%"
text="City tax" />
<total>10.24</total>
</guest>
<hotel>
<extracomponent amount="0.48"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="5%"
text="VAT" />
<extracomponent amount="0.24"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="2.5%"
text="City tax" />
<total>10.24</total>
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>4812008729</roomreservation_id>
<smoking>0</smoking>
<totalprice>10</totalprice>
</room>
<status>new</status>
<time>15:12:44</time>
<totalprice>10</totalprice>
</reservation>
</reservations>Understanding tax remittance using Payments Clarity Package v2
Based on the property’s location and tax configuration, multiple taxes could apply for each reservation or booking. If the property participates in Payments by Booking.com, and is paid via virtual credit card (VCC), then Booking.com is obligated to collect and pay certains taxes on behalf of the property whereas the property is directly obligated to remit certain other taxes.
The ability to support showing reservations that details the division of tax responsibilities between Booking.com and the property is known as split tax obligation and remittance.
You can find more details of the various scenarios in the Summary of different combinations of included value.
The following outlines the three types of tax remittances and reservation message examples of each type.
- Booking remits all taxes
- Partner remits all taxes
- Split tax obligation between Booking.com and partner
Booking.com remits all taxes and fees
Booking.com remits taxes when the property has all taxes and fees defined the same way as scenario 3 in Summary of different combinations of included value and uses Payments by Booking.com virtual credit card (VCC) payouts.
| Scenario | Guest View | Property View | Payments by Booking behaviour |
|---|---|---|---|
| 3 | Included | Excluded | - Fees/tax was collected from the guest during booking. - Fees/tax is withheld and will be paid directly to the authorities and not to property. |
Consider the following scenario - Property ABC has the following tax configurations:
Booking.com remits:
- 5% Local Community Impact Fee
- 1.5% Recreation and Public Improvement Promotion Tax
- 2% Parks Recreation and Community Economic Development Tax
The following reservation message snippet shows that all the three taxes are remitted by Booking.com. The actual tax names and tax amounts of your properties will differ, depending on the specifics, such as the property’s location and tax configuration.
Expand this section to view the B.XML response example when Booking.com remits all taxes and fees.
<price_details>
<guest>
<extracomponent amount="0.06"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="5.00%"
text="Local Community Impact Fee (Withheld Tax)" />
<extracomponent amount="0.02"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="1.50%"
text="Recreation and Public Improvement Promotion Tax (Withheld Tax)" />
<extracomponent amount="0.03"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="2.00%"
text="Parks Recreation and Community Economic Development Tax (Withheld Tax)" />
<total>1.36</total>
</guest>
<hotel>
<extracomponent amount="0.06"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="5.00%"
text="Local Community Impact Fee (Withheld Tax)" />
<extracomponent amount="0.02"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="1.50%"
text="Recreation and Public Improvement Promotion Tax (Withheld Tax)" />
<extracomponent amount="0.03"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="2.00%"
text="Parks Recreation and Community Economic Development Tax (Withheld Tax)" />
<total>1.25</total>
</hotel>
</price_details>Partner remits all taxes and fees
The partner remits taxes when the property has all taxes and fees defined the same way as scenario 4 in Summary of different combinations of included value and uses Payments by Booking.com virtual credit card (VCC) payouts.
| Scenario | Guest View | Property View | Payments by Booking behaviour |
|---|---|---|---|
| 4 | Included | Included | - Fees/tax was collected from the guest during booking. - Fees/tax will be paid out to property. |
Consider the following scenario - Property ABC has the following tax configurations:
Partner needs to remit:
- 2% Occupancy tax
- 3% Tourism tax
The following reservation message snippet shows that the partner needs to remit both the taxes. The actual tax names and tax amounts of your properties will differ, depending on the specifics, such as the property’s location and tax configuration.
Expand this section to view the B.XML response example when the partner remits all taxes and fees.
<price_details>
<guest>
<extracomponent amount="0.03"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="2.00%"
text="Occupancy Tax" />
<extracomponent amount="0.04"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="3.00%"
text="Tourism Tax" />
<total>1.31</total>
</guest>
<hotel>
<extracomponent amount="0.03"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="2.00%"
text="Occupancy Tax" />
<extracomponent amount="0.04"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="3.00%"
text="Tourism Tax" />
<total>1.31</total>
</hotel>
</price_details>
Split tax obligations and remittance
Split tax obligations and remittance occur when the property has taxes and fees defined the same way as scenarios 3 and 4 in Summary of different combinations of included value, respectively, and uses Payments by Booking.com virtual credit card (VCC) payouts.
| Scenario | Guest View | Property View | Payments by Booking behaviour |
|---|---|---|---|
| 3 | Included | Excluded | - Fees/tax was collected from the guest during booking. - Fees/tax is withheld and will be paid directly to the authorities and not to property. |
| 4 | Included | Included | - Fees/tax was collected from the guest during booking. - Fees/tax will be paid out to property. |
Consider the following scenario - Property ABC has the following tax configurations:
Booking.com remits:
- 5% Local Community Impact Fee
- 1.5% Recreation and Public Improvement Promotion Tax
- 1.5% Parks Recreation and Community Economic Development Tax
Partner needs to remit:
- 2% Tourism Tax
The following reservation message snippet shows the taxes remitted by Booking.com versus by the property. The actual tax names and tax amounts of your properties will differ, depending on the specifics, such as the property’s location and tax configuration.
Expand this section to view the B.XML response example when split tax obligations and remittance occurs.
<price_details>
<guest>
<extracomponent amount="0.06"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="5.00%"
text="Local Community Impact Fee (Withheld Tax)"/>
<extracomponent amount="0.02"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="1.50%"
text="Recreation and Public Improvement Promotion Tax (Withheld Tax)" />
<extracomponent amount="0.02"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="1.50%"
text="Parks Recreation and Community Economic Development Tax (Withheld Tax)" />
<extracomponent amount="0.03"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="2.00%"
text="Tourism Tax" />
<total>1.38</total>
</guest>
<hotel>
<extracomponent amount="0.06"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="5.00%"
text="Local Community Impact Fee (Withheld Tax)" />
<extracomponent amount="0.02"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="1.50%"
text="Recreation and Public Improvement Promotion Tax (Withheld Tax)" />
<extracomponent amount="0.02"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="1.50%"
text="Parks Recreation and Community Economic Development Tax (Withheld Tax)" />
<extracomponent amount="0.03"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="2.00%"
text="Tourism Tax" />
<total>1.28</total>
</hotel>
</price_details>Contact us
For questions about capability assessment or to schedule one, contact your Partner Business Manager/Account Manager or send us an email at pcp.capability.assessment@booking.com.
If you have questions about testing, please contact the Connectivity Support team.