Use cases and best practices

This page describes all the different use cases you can follow using the Payments API.

Calling Payments API

Depending on the use cases you want to follow, there are different ways to use the Payments API endpoints:

• In case of endpoints that return information per reservation, once an update on a reservation is available, we send you a push notification in real time. Upon receiving it, you can parse the notification payload to read such values as the reservation ID and then call the respective endpoint using these values to get the required information.

• In case of endpoints that return information per property, we don't send you push notifications. Instead, you can call the respective endpoint with the frequency you prefer to get required information.

Understanding net and gross payouts

All our endpoints and notifications support both gross and net payouts. See below to understand the difference between the two types:

• All VCC payouts are gross by definition.
• If the payout includes a commission, it's a gross payout (payout_type= GROSS).
• If Booking.com holds back the commission and performs the payout after deducting the commission, it's a net payout (payout_type= NET).
• In case of a payout method switch, in very rare cases, the payout happens partially on the VCC and partially via a bank transfer. In this case, if the bank transfer is gross, it's a gross payout, but if the bank transfer is net, payout_type has the status UNKNOWN in the response.

Get payout details per reservation

• Notification types: PAYOUT_UPDATE and PAYOUT_METHOD_UPDATE
• Endpoint: /reservations/{reservation-id}

Once a payout-related update is available for a reservation, you receive a notification in real time informing you about it.

Query the /reservations/{reservation-id} endpoint to get payout details for a reservation, such as an estimated amount to be collected at the property, payout amount and status, commissions and charges, VCC or BT payout details, or price breakdown.

See Getting payout details for reservation.

Understanding reservation price breakdowns

• Notification type: PAYOUT_UPDATE
• Endpoint: /reservations/{reservation-id}/breakdown

If there is a change in the price breakdown of a reservation, you receive a notification in real time informing you about a change in the given reservation.

By calling this endpoint, you get a detailed price breakdown for this reservation, such as the VAT, applicable taxes, and fees, per each room the guest booked.

To get the latest price breakdown for a reservation, query the /reservations/{reservation-id}/breakdown endpoint.

See Getting price breakdown for reservation.

Get details on BT payout changes

• Notification type: BANK_TRANSFER_UPDATE
• Endpoint: /reservations/{reservation-id}/payout/bt

If there is a change in the bank transfer payout details for a given reservation, such as if the payout status, date or amount have changed, you receive a notification in real time informing you about a change in the bank transfer payout associated with the reservation.

To get details on the bank transfer payout changes for a reservation, query the /reservations/{reservation-id}/payout/bt endpoint.

See Getting BT payout details for reservation.

Get details VCC payout changes

• Notification type: VIRTUAL_CREDIT_CARD_UPDATE
• Endpoint: /reservations/{reservation-id}/payout/vcc

If there is a change in the VCC payout details for a given reservation, such as if a VCC is activated, successfully authorized, or its balance has changed, you receive a notification in real time informing you about a change in the VCC associated with the reservation.

To get details on the VCC payout changes for a reservation, query the /reservations/{reservation-id}/payout/vcc endpoint.

See Getting VCC payout details for reservation.

Get details on refundable VCCs per property

• Notification type: N/A
• Endpoint: /properties/{property-id}/refundable-vccs

With this use case, you don't receive automatic notifications. Instead, you need to query the endpoint with a preferred frequency. The recommended frequency is once in 24 hours (per property).

Querying this endpoint is useful in situations where the partner needs to know to which VCCs they need to refund money to.

For example, if the guest canceled their reservation and both Booking.com and the property have agreed to waive off the cancellation fee, Booking.com has to collect the cancellation fee amount from the property, so the partner has to load the refund amount into the given VCC.

To get a list of refundable VCC IDs per property ID, query the /properties/{property-id}/refundable-vccs endpoint.

See Managing refundable vccs.

Get details on chargeable VCCs per property

• Notification type: N/A
• Endpoint: /properties/{property-id}/chargeable-vccs

With this use case, you don't receive automatic notifications. Instead, you need to query the endpoint with a preferred frequency. The recommended frequency is once in 12 hours (per property).

Querying this endpoint is useful in situations where the partner needs to know if they have some funds left on their VCCs that they can still charge.

To get a list of chargeable VCC IDs per property ID, query the /properties/{property-id}/chargeable-vccs endpoint.

See Managing chargeable vccs.