Receiving notifications

To start receiving notifications, follow the instructions from the Notification service documentation.

The Payments API is currently only applicable for properties who use the Payments by Booking.com payment method and who have already implemented the Reservations API.
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.

Integrating the Payments API notifications is optional, allowing you to use the API without them. However, we strongly recommend integrating these notifications to minimize system load and maximize the API's benefits.

Upon receiving a notification that an update is available, you query the respective Payments Details API endpoints to get the actual update. This page explains what you need to do to start receiving the notifications.

Alternatively, if you're unable to integrate notifications, you can call the Payments Details API upon receiving the reservation confirmation information from the Reservations API. This is only available for Payments by Booking (PbB) reservations. To learn if a reservation is a PbB one, check the confirmation information:

For B.XML, payment_type is set to "payment_on_Booking.com"
For OTA, GuaranteeType is set to "PrePay"

In case of the Payments Chargeable and Payments Refundable APIs, you don't receive notifications and query the endpoints with a preferred frequency.

Notification types

We're sending notifications of these four types:

PAYOUT_UPDATE
PAYOUT_METHOD_UPDATE
VIRTUAL_CREDIT_CARD_UPDATE
BANK_TRANSFER_UPDATE (Now supported for both gross and net payouts)

To learn when these notifications are sent, see the respective sections below.

Each notification has the following two elements:

Metadata: Describes the payload type, UUID, as well as any other information that might be relevant for processing the notification. A common metadata format applies across all notification message types.
Payload: Represents the actionable notification content. It's different for each type of notification message.

Notification details

`PAYOUT_UPDATE`

Notifications related to bank transfer payouts are now fully supported.

A notification of this type is sent in case of updates to payout details, such as a change in the total payout amount or commission and charges.

To fetch data upon receiving this notification, call the Payments Detail API endpoints using reservationId.

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "PAYOUT_UPDATE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "timestamp": "2023-12-10T10:01:322Z",
        "propertyId": 10345,
        "reservationId": 432647264
    }
}

metadata:

uuid: Stores the UUID for this notification. Useful when contacting Connectivity Support Executives to inquire about a given message.
type: Type of the message.
payloadVersion: Version of the payload JSON element. 1.0 for now, subject to change.

payload:

payload.reservationId: Refers to the Booking.com ID of the hotel reservation.
payload.propertyId: Refers to the Booking.com ID of the property that the reservation belongs to.
payload.timestamp: Timestamp in which the notification is triggered, in ISO-8601 format.

`PAYOUT_METHOD_UPDATE`

A notification of this type is sent in case the property wants to switch from one payout method to another, such as from VCC to BT. Once the payout method is updated in the Booking.com system for the given property, we send a notification informing that the payout method has been changed.

To fetch data upon receiving this notification, call the Payments Detail API endpoints using reservationId.

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "PAYOUT_METHOD_UPDATE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "timestamp": "2023-12-10T10:01:322Z",
        "propertyId": 10345,
        "reservationId": 432647264
    }
}

metadata:

uuid: Stores the UUID for this notification. Useful when contacting Connectivity Support Executives to inquire about a given message.
type: Type of the message.
payloadVersion: Version of the payload JSON element. 1.0 for now, subject to change.

payload:

payload.reservationId: Refers to the Booking.com ID of the hotel reservation.
payload.propertyId: Refers to the Booking.com ID of the property that the reservation belongs to.
payload.timestamp: Timestamp in which the notification is triggered, in ISO-8601 format.

`VIRTUAL_CREDIT_CARD_UPDATE`

A notification of this type is sent in case of updates to VCC details, such as if the current balance changes or the card status get updated.

To fetch data for this notification, call the /reservations/{reservation-id}/payout/vcc?vcc-id={vcc-id} endpoint using reservation-id or vcc-id:

If you call the endpoint using vcc-id, you receive data for the given virtual credit card.
If you call the endpoint using reservation-id, you receive data for all virtual credit cards that belong to this reservation-id (including closed ones).

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "VIRTUAL_CREDIT_CARD_UPDATE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "timestamp": "2023-12-10T10:01:322Z",
        "propertyId": 10345,
        "reservationId": 432647264,
        "vccId": "FC70575E-ED0E-11EE-B5FA-B675273SHDDBC"
    }
}

metadata:

uuid: Stores the UUID for this notification. Useful when contacting Connectivity Support Executives to inquire about a given message.
type: Type of the message.
payloadVersion: Version of the payload JSON element. 1.0 for now, subject to change.

payload:

payload.reservationId: Refers to the Booking.com ID of the hotel reservation.
payload.propertyId: Refers to the Booking.com ID of the property that the reservation belongs to.
payload.vccId: Refers to the Booking.com ID of the VCC that belongs to this reservation ID.
payload.timestamp: Timestamp in which the notification is triggered, in ISO-8601 format.

`BANK_TRANSFER_UPDATE`

This notification is now supported for both gross and net payouts.

A notification of this type is sent in case of updates to a BT payout, such as if the BT payout status changes.

To fetch data upon receiving this notification, call the /reservations/{reservation-id}/payout/bt endpoint using reservationId.

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "BANK_TRANSFER_UPDATE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "timestamp": "2023-12-10T10:01:322Z",
        "propertyId": 10345,
        "reservationId": 432647264
    }
}

metadata:

uuid: Stores the UUID for this notification. Useful when contacting Connectivity Support Executives to inquire about a given message.
type: Type of the message.
payloadVersion: Version of the payload JSON element. 1.0 for now, subject to change.

payload:

payload.reservationId: Refers to the Booking.com ID of the hotel reservation.
payload.propertyId: Refers to the Booking.com ID of the property that the reservation belongs to.
payload.timestamp: Timestamp in which the notification is triggered, in ISO-8601 format.