Vrbo on Rapid integration guide
A guide to the Vrbo integration process for partners
Overview
This article offers a guide to the Rapid 3.0 Vrbo integration process including how it works, example API requests and responses, limitations, error handling, and FAQs.
This guide is geared toward our recommended Vrbo supply offering. For advanced use cases please see the Advanced Integration Guide below.
Scenario 1: Refundable damage deposits (RDD)
Some Vrbo properties require collection of a damage deposit prior to arrival, providing a refund post-departure based on property condition.
About RDDs
- Properties requesting RDDs may occur more frequently during periods of high compression such as holidays.
- About 2% of properties require a refundable damage deposit pre-arrival.
- RDD amount and requirement may vary by geography and season.
Guests must be informed:
- Payment of the damage deposit is made with the last scheduled payment (or at time of book if single payment).
- Refund of damage deposits will be made within 12 days of departure based on the host's inspection.
- Vrbo will send a damage invoice to the guest in case of damage.
- Refundable damage deposit amount must be displayed on check-out.
- The RDD amount displayed in Rapid Shop is an estimate. The amount from Rapid Price Check is the amount which will be charged to the guest, and must be displayed to the guest during check-out.
Partner merchant of record:
- We recommend RDDs are excluded when partner provides payment via Virtual Card unless they are able to facilitate the collection and refund of the damage deposit with the guest.
- Partners are responsible for displaying the amount to the guest and collecting/refunding accordingly.
Example:
"rates": [
{
"refundable_damage_deposit": {
"value": "150.00",
"currency": "USD"
}
}
]Scenario 2: Customer credit card
Use of customer credit cards requires additional validation and communication to the guest.
Address validation
- Vrbo bookings require different address validation than Rapid lodging.
See below for details:
| Countries with Postal Codes | Countries without Postal Codes | Countries with Postal Codes and Additional Details |
|---|---|---|
 |  |  |
| Afghanistan | Angola | Australia: State |
| Åland Islands | Antigua and Barbuda | Brazil: State (+Neighborhood on BR POSA) and CPF/CNPJ |
| Albania | Aruba | Canada: Province |
| American Samoa | Bahamas | Japan: State and Address line 2 |
| Andorra | Belize | Spain: National ID |
| Anguilla | Benin | United States: State |
| Antarctica | Botswana | |
| Argentina | Burkina Faso | |
| Armenia | Burundi | |
| Austria | Cameroon | |
| Azerbaijan | Central African Republic | |
| Bahrain | Comoros | |
| Bangladesh | Congo | |
| Barbados | Congo, the Democratic Republic of the | |
| Belarus | Cook Islands | |
| Belgium | Côte d'Ivoire | |
| Bermuda | Djibouti | |
| Bhutan | Dominica | |
| Bolivia, Plurinational State of† | Equatorial Guinea | |
| Bosnia and Herzegovina | Eritrea | |
| Bouvet Island | Fiji | |
| British Indian Ocean Territory | French Southern Territories | |
| Brunei Darussalam | Gambia | |
| Bulgaria | Ghana | |
| Cambodia | Grenada | |
| Cape Verde | Guinea | |
| Cayman Islands | Guyana | |
| Chad | Hong Kong | |
| Chile | Ireland†† | |
| China | Kenya | |
| Christmas Island | Kiribati | |
| Cocos (Keeling) Islands | Macao | |
| Colombia | Malawi | |
| Costa Rica | Mali | |
| Croatia | Mauritania | |
| Cuba | Mauritius | |
| Cyprus | Montserrat | |
| Czech Republic | Nauru | |
| Denmark | Niue | |
| Dominican Republic | Panama | |
| Ecuador | Qatar | |
| Egypt | Rwanda | |
| El Salvador | Saint Kitts and Nevis | |
| Estonia | Saint Lucia | |
| Ethiopia | Sao Tome and Principe | |
| Falkland Islands (Malvinas) | Seychelles | |
| Faroe Islands | Sierra Leone | |
| Finland | Solomon Islands | |
| France | Somalia†† | |
| French Guiana | South Africa†† | |
| French Polynesia | Suriname | |
| Gabon | Syrian Arab Republic | |
| Georgia | Tanzania, United Republic of | |
| Germany | Timor-Leste | |
| Gibraltar | Tokelau | |
| Greece | Tonga | |
| Greenland | Trinidad and Tobago | |
| Guadeloupe | Tuvalu | |
| Guam | Uganda | |
| Guatemala | United Arab Emirates | |
| Guinea-Bissau | Vanuatu | |
| Haiti | Yemen | |
| Heard and McDonald Islands† | Zimbabwe | |
| Holy See (Vatican City State) | ||
| Honduras | ||
| Hungary | ||
| Iceland | ||
| India | ||
| Indonesia | ||
| Iran, Islamic Republic of | ||
| Iraq | ||
| Israel | ||
| Italy | ||
| Jamaica | ||
| Jordan | ||
| Kazakhstan | ||
| Korea, Republic of | ||
| Kuwait | ||
| Kyrgyzstan | ||
| Lao People's Democratic Republic | ||
| Latvia | ||
| Lebanon | ||
| Lesotho | ||
| Liberia | ||
| Libya† | ||
| Liechtenstein | ||
| Lithuania | ||
| Luxembourg | ||
| Macedonia, the former Yugoslav Republic of | ||
| Madagascar | ||
| Malaysia | ||
| Maldives | ||
| Malta | ||
| Marshall Islands | ||
| Martinique | ||
| Mayotte | ||
| Mexico | ||
| Micronesia, Federated States of | ||
| Moldova, Republic of | ||
| Monaco | ||
| Mongolia | ||
| Montenegro | ||
| Morocco | ||
| Mozambique | ||
| Myanmar | ||
| Namibia | ||
| Nepal | ||
| Netherlands | ||
| New Caledonia | ||
| New Zealand | ||
| Nicaragua | ||
| Niger | ||
| Norfolk Island | ||
| Northern Mariana Islands | ||
| Norway | ||
| Oman | ||
| Palau | ||
| Palestine, State of | ||
| Papua New Guinea | ||
| Paraguay | ||
| Peru | ||
| Philippines | ||
| Pitcairn | ||
| Poland | ||
| Portugal | ||
| Puerto Rico | ||
| Réunion | ||
| Romania | ||
| Russian Federation | ||
| Saint Barthélemy | ||
| Saint Helena, Ascension and Tristan da Cunha | ||
| Saint Pierre and Miquelon | ||
| Saint Vincent and the Grenadines | ||
| Samoa | ||
| San Marino | ||
| Senegal | ||
| Serbia | ||
| Serbia and Montenegro | ||
| Singapore | ||
| Slovakia | ||
| Slovenia | ||
| South Georgia and the South Sandwich Islands | ||
| Sri Lanka | ||
| Sudan | ||
| Svalbard and Jan Mayen | ||
| Swaziland | ||
| Sweden | ||
| Switzerland | ||
| Taiwan, Province of China | ||
| Tajikistan | ||
| Thailand | ||
| Togo† | ||
| Tunisia | ||
| Turkey | ||
| Turkmenistan | ||
| Turks and Caicos Islands | ||
| Ukraine | ||
| United Kingdom | ||
| United States Minor Outlying Islands | ||
| Uruguay | ||
| Uzbekistan | ||
| Venezuela, Bolivarian Republic of | ||
| Viet Nam | ||
| Virgin Islands, British | ||
| Virgin Islands, U.S. | ||
| Wallis and Futuna | ||
| Western Sahara | ||
| Zambia |
†Countries with partial availability of zip/postal codes but maintained as mandatory on Vrbo check-out.
††Countries with partial availability of zip/postal codes but that we don't have as mandatory.
Guests must be informed
- Description of who will charge their card.
- Bank charges: Guests should be reminded that their bank may charge fees for international transactions.
- Refunds: Guest should be reminded that exchange rate fluctuations may impact the refund amount.
Damages: Guests must be informed of the maximum charge amount and charge/refund timing
- Maximum charge amount is provided in the Rapid Shop response under
refundable_damage_deposit. - Damages will be charged to the guest card if the property is damaged, up to the specified maximum.
- Vrbo will send a damage invoice to the guest in case of damage.
Booking Error: Shop country differs from customer country (billing address)
The price for a Vrbo property can vary based on the location of the guest. The location is determined by the billing address input by the guest during check-out. As a result, partners must detect this mismatch prior to submitting the booking to avoid a booking error. If countries vary, partners must obtain a new price based on the guest's billing country.
Option 1: Prior to submitting the booking partners should compare the shopped country with the guest billing country. If different, re-shop using the billing address country, display updated price and allow guest to re-submit the booking.
Option 2: Limit billing address fields on check-out page to only the POSa country.
Scenario 3: Payment schedules
Vrbo properties sometimes collect payment based on a pre-defined schedule.
About deposits (payment schedules)
- ~25% of properties provide a payment schedule for longer booking windows >3 months.
- ~15% of properties provide a payment schedule for shorter booking windows <1 month.
Guests must be informed
- Payment schedule detail should be shown during shop/check-out, ideally as a visual timeline view.
Example:
"deposits": [
{
"value": "412.10",
"due": "2023-05-17",
"currency": "USD"
},
{
"value": "236.17",
"due": "2023-08-24",
"currency": "USD"
}
]
- Guests must be informed that they are responsible for making payment on the Vrbo site according to the provided schedule or risk cancellation by the host.
- Vrbo will send email reminders prior, on, and after the payment due date to ensure the guest is aware of the payment requirement.
Combined with refundable ramage reposits:
- When RDD is required, it will be charged as part of the last scheduled payment. If single-payment, it will be collected at time of book.
Combined with partner merchant of record:
- Due to manual payment requirement on Vrbo.com, we do not recommend properties with payment schedules be booked as partner as Merchant of Record.
All Vrbo bookings are required to include the customer email to facilitate direct communication between the property manager and the traveler. Use of a partner/agent email risks booking cancellation by the host in some cases.
Examples of property manager communications include:
- Welcome message and introduction to the property manager
- Contact details
- Policies and Know Before You Go
- Address and directions
- Key box code
- Payment schedule
- Rental agreement (may be required or property manager could cancel booking)
- Passport photo request (may be required or property manager could cancel booking)
- Cancel confirmation
- Refund confirmation
Example:
