Understanding the Payments API
The Payments API provides comprehensive payment and payout-related information.
You can get details on reservations with the checkout date in the last 18 months.
The Payments API is currently only applicable for properties who use the Payments by Booking.com (PbB) payment method and who have already implemented the Reservations API. To check if a reservation is a PbB one, see Receiving notifications.
Also, the API doesn't support Pay at Property (P@P) reservations where guests choose to pay for their accommodation upon arrival at the property rather than at the time of booking.
The API now supports Stripe as the payout method with no limitations.
What is possible with the Payments API?
| API category | Description | Notifications |
|---|---|---|
| Payments Details API | Provides comprehensive payout information for accommodation reservations, which includes the payout type, payout status along with additional payout information. It also provides a detailed price breakdown, a clear indication of what Booking.com needs to pay to the partner, and an estimated amount of what the partner needs to collect from the guest. | You receive a notification once an update is available and then query the respective endpoints. |
| Payments Refundable API | Provides information on refundable VCCs at property level. | You don't receive notifications and query the endpoint with the preferred frequency. |
| Payments Chargeable API | Provides information on chargeable VCCs at property level. | You don't receive notifications and query the endpoint with the preferred frequency. |
Notifications you receive
The notifications listed below are only sent if you integrated the notifications functionality as described in Receiving notifications.
We're sending notifications of these four types:
PAYOUT_UPDATEPAYOUT_METHOD_UPDATEVIRTUAL_CREDIT_CARD_UPDATEBANK_TRANSFER_UPDATE(Now supported for both gross and net payouts)
To learn more about the notification types and the endpoints associated with them, see Receiving notifications.
Choosing between Payments API and Payments Clarity Package v2
Booking.com offers two solutions, Payments API and Payments Clarity Package v2 (PCP v2), that share the same core goal: to give connected partners clear, actionable payment information for each reservation. While both solutions are valuable, each is better suited to certain situations, so you should choose the solution based on your use case. The information outlined here should help you make this choice.
Typical scenarios and your options
| Scenario | Your options |
|---|---|
| Partner has all or majority of their properties on Payments by Booking (PbB) | Use the Payments API. |
| Partner needs to match reservation-level payout amounts to their financial system | Use the Payments API as it exposes reservation-level payout data that can be used for reconciliation. |
| Partner integrates only reservations (not separate payments endpoints) | Use PCP v2 as it lets you keep a single reservations feed with added payment clarity fields, including tax/fee breakdowns in the reservation message. |
| Partner relies on agency (Pay at Property) flows. | Use PCP v2 as it carries clarity for agency reservations inside the reservation payload. The Payments API agency coverage is being expanded in phases, so confirm timing and scope if you plan to rely on it for agency now. |
| You operate in countries where Booking.com collects and remits certain reservation‑based taxes on your behalf (see "Tax remittance management" below) and require line-item tax base for reporting | Both solutions work. If you need tax base details at the reporting level, PCP v2 currently addresses this in reservations. As of November 2025, the Payments API supports the same tax remittance flows in Canada and Malaysia and provides payout and price breakdown information for Payments by Booking (PbB) reservations. |
| Partner wants to reduce “0 balance” confusion for VCCs | Integrate the VIRTUAL_CREDIT_CARD_UPDATE notification provided by the Payments API and then call Payments API’s VCC-related endpoints. This flow provides timely VCC balance and status updates. |
| Partner's fees are per person or occupancy-based | Both solutions work. Note that fees configured as “excluded” are to be collected by the property at check-in/out. |
Tax remittance management
Tax remittance markets are markets where Booking.com calculates, withholds, and remits reservation‑based taxes on partner's behalf (e.g., sales/occupancy, city/tourist, or partner-facing withholding), instead of leaving this entirely to the partner.
As of November 2025, the Payments API supports our tax remittance flows in Canada and Malaysia.
Main URL and use of shortened endpoint paths
The Payments API's main URL is https://payments-api.booking.com. All shortened endpoint paths imply that you must add the main URL.
Authentication
The Payments API uses the same authentication methods as other APIs.
Going live
Before you go live with your API integration, you'll need to meet certain requirements. For more information, see Going Live.
Contact us
Need help integrating with the Payments API? The experts in our Connectivity Support team are here to help.
Do you want us to improve this page? Click Yes | No in the Was this page helpful? box at the bottom of this page.