Managing payment and payout details

The Payment 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.

Quick actions

Getting payout details for reservation
Getting price breakdown for reservation
Getting VCC payout details for reservation
Getting BT payout details for reservation

Getting payout details for reservation

GET https://payments-api.booking.com/connectivity-payments/reservations/{reservation-id}

The GET /connectivity-payments/reservations/{reservation-id} request enables you get payout details on a reservation such as an estimated amount to be collected at the property, the payout status and amount, commissions and charges, VCC or BT payout details, and price breakdown.

If a payout-related update is available, you receive a notification of type PAYOUT_UPDATE or PAYOUT_METHOD_UPDATE, depending on the kind of update, and then you can query the endpoint to get the details.

Path parameters

The following table describes what elements you must add as path parameters:

Element	Description	Type	Required/Optional
`reservation-id`	Specifies the identifier of the reservation.	string	required

Headers

Element	Description	Type	Required/Optional
`accept-version`	Specifies the version of the API you want to use.	string	optional

Response body example

The following is a successful response body example:

{
  "meta": {
    "ruid": "1"
  },
  "data": {
    "reservation_id": "4482006106",
    "property_id": "367104",
    "payout_type": "NET",
    "total_price_of_reservation": {
      "total_amount_paid": {
        "currency": "EUR",
        "value": "6877",
        "decimals": 2
      },
      "total_amount_to_collect_at_property": {
        "currency": "EUR",
        "value": "6",
        "decimals": 0
      }
    },
    "partner_payout": {
      "total_payout": {
        "currency": "EUR",
        "value": "5749",
        "decimals": 2
      },
      "commissionable_price": {
        "currency": "EUR",
        "value": "6877",
        "decimals": 2
      },
      "commissions_and_charges": {
        "currency": "EUR",
        "value": "1128",
        "decimals": 2
      }
    },
    "payout": {
      "bank_transfers": [],
      "virtual_credit_cards": [
        {
          "activation_date": "2024-10-09",
          "id": "7ca61d4e-c905-46eb-ae5e-b384416d6fbb",
          "current_balance": {
            "currency": "EUR",
            "value": "0",
            "decimals": 0
          },
          "expiration_date": "2025-10-10",
          "status": "FULLY_CHARGED",
          "card_details": {
            "cvc": "737",
            "card_name": "Booking.com",
            "card_number": "12345678998765432",
            "card_expiry": "03/30"
          }
        }
      ]
    },
    "price_breakdown": [
      {
        "room_reservation_id": "5214001415",
        "charges": [
          {
            "type": "VAT",
            "amount": {
              "currency": "EUR",
              "value": "389",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "TRUE"
          },
          {
            "type": "City tax",
            "amount": {
              "currency": "EUR",
              "value": "6",
              "decimals": 0
            },
            "is_already_collected_from_guest": "FALSE",
            "is_included_total_partner_payout": "FALSE"
          },
          {
            "type": "COMMISSION",
            "amount": {
              "currency": "EUR",
              "value": "1032",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "FALSE"
          }
        ]
      }
    ]
  },
  "errors": [],
  "warnings": []
}

Response body elements

The following table describes the response elements:

Element	Description	Type
`data`	Contains the response data.	object
: `reservation_id`	Specifies the identifier of the reservation.	string
: `property_id`	Specifies the identifier of the property.	string
: `payout_type`	Specifies the type of payout: `GROSS`, `NET`, or `UNKNOWN`.	string
:: `payout_status`	Specifies the status of the payout: `PENDING`, `PAID`, `PARTIALLY_PAID`, `CANCELLED`, or `UNKNOWN`.	string
: `total_price_of_reservation`	Contains information on the total cost of the reservation for the guest.	object
:: `total_amount_paid`	Contains information on the total amount the guest paid to Booking.com.	object
::: `value`	Cost amount.	string
::: `currency`	Currency of the amount.	string
::: `decimals`	Number of decimals in the amount.	string
:: `total_amount_to_collect_at_property`	Contains information on the estimated amount the partner needs to collect from the guest at checkin.	object
::: `value`	Amount to be collected.	string
::: `currency`	Currency in which the amount is to be collected.	string
::: `decimals`	Number of decimals in the amount.	string
: `partner_payout`	Contains information on what Booking.com has to pay out to the partner.	object
:: `total_payout`	Contains information on the total amount that will be paid to the partner.	object
::: `value`	Payout amount.	string
::: `currency`	Currency of the amount.	string
::: `decimals`	Number of decimals in the amount.	string
:: `commissionable_price`	Contains information on the total commissionable price.	object
::: `value`	Price amount.	string
::: `currency`	Currency of the price.	string
::: `decimals`	Number of decimals in the amount.	string
:: `commissions_and_charges`	Contains information on the total amount of commission and other charges such as fees.	object
::: `value`	Amount of the commission and other charges.	string
::: `currency`	Currency of the amount.	string
::: `decimals`	Number of decimals in the total amount.	string
: `payout`	Contains payout details.	object
:: `bank_transfers`	Contains information on the bank transfer payout to be transferred.	object
:: `amount`	Contains information on the bank transfer payout amount.	object
:::: `value`	Payout amount.	string
:::: `currency`	Currency of the amount.	string
:::: `decimals`	Number of decimals in the amount.	string
:: `status`	Specifies the status of the bank transfer payout: `PENDING`, `PAID`, or `UNKNOWN`.	string
:: `payout_date`	Specified the date the amount is to be paid out to the partner. Format: YYYY-MM-DD.	string
: `virtual_credit_cards`	Contains details on the VCCs.	object
:: `id`	Specifies the identifier of the VCC.	string
:: `activation_date`	Specifies the date when the VCC is activated.	string
:: `current_balance`	Contains information on the current balance of the VCC.	object
::: `value`	Amount on the VCC.	string
::: `currency`	Currency of the amount.	string
::: `decimals`	Number of decimals in the amount.	string
:: `expiration_date`	Specifies the date when the VCC gets expired as set by Booking.com. Format: YYYY-MM-DD.	string
:: `status`	Specifies the status of the VCC: `NOT_LOADED`, `FUNDED`, `CANCELLED`, `AVAILABLE`, `FULLY_CHARGED`, `PARTIALLY_CHARGED`, or `UNKNOWN`. For more info, see VCC statuses.	string
:: `card_details`	Contains details of the VCC. Also see Limitations with sharing card details.	object
::: `cvc`	CVC of the VCC.	string
::: `card_name`	Name of the VCC.	string
::: `card_type`	Type of the VCC.	string
::: `card_number`	Number of the VCC.	string
:: `card_expiry`	Specifies the date when the VCC gets expired as set by the card issuer. Format: MM/YY.	string
: `price_breakdown`	Contains a price breakdown for the given reservation, per each room the guest booked.	object
:: `room_reservation_id`	Specifies the identifier of the booked room.	string
:: `charges`	Contains a list of charges applicable to this room.	object
::: `type`	Specifies the type of charge, such as `city_tax`, `resort_fees`, or `internet_fees`.	string
::: `amount`	Contains information on the total amount of all charges.	object
:::: `value`	Total amount of charges.	string
:::: `currency`	Currency of the amount.	string
:::: `decimals`	Number of decimals in the amount.	string
::: `is_already_collected_from_guest`	If set to `TRUE`, it indicates that the charged amount has already been collected from the guest, and the partner doesn't need to collect anything. Otherwise, it's set to `FALSE`, and the partner has to collect the money at checkin. If set to `UNKNOWN`, no information is available. For more, see Explanation of payment flags from response.	enum
::: `is_included_total_partner_payout`	If set to `TRUE`, it indicates that the charged amount is included in the payout and will be transferred to the partner. Otherwise, it's set to `FALSE`, which means the charged amount is intended for another party, such as the government. If set to `UNKNOWN`, no information is available. For more, see Explanation of payment flags from response.	enum
`errors`	Contains potential errors. These can help you understand what went wrong with your request. For more information, see Response codes.	array
`warnings`	Contains potential warnings. These can help you improve your requests. Also see Limitations with sharing card details.	array

Getting price breakdown for reservation

GET https://payments-api.booking.com/connectivity-payments/reservations/{reservation-id}/breakdown

The GET /connectivity-payments/reservations/{reservation-id}/breakdown request enables you to get a detailed price breakdown for a given reservation, such as the VAT, applicable taxes, and fees, per each room the guest booked.

If a payout-related update is available, you receive a notification of type PAYOUT_UPDATE, and then you can query the endpoint to get the details.

Path parameters

The following table describes what elements you must add as path parameters:

Element	Description	Type	Required/Optional
`reservation-id`	Specifies the identifier of the reservation.	string	required

Headers

Element	Description	Type	Required/Optional
`accept-version`	Specifies the version of the API you want to use.	string	optional

Response body example

The following is a successful response body example:

{
  "meta": {
    "ruid": "1"
  },
  "data": {
    "reservation_id": "4482006106",
    "property_id": "367104",
    "payout_type": "NET",
    "total_price_of_reservation": {
      "total_amount_paid": {
        "currency": "EUR",
        "value": "6877",
        "decimals": 2
      },
      "total_amount_to_collect_at_property": {
        "currency": "EUR",
        "value": "6",
        "decimals": 0
      }
    },
    "partner_payout": {
      "total_payout": {
        "currency": "EUR",
        "value": "5749",
        "decimals": 2
      },
      "commissionable_price": {
        "currency": "EUR",
        "value": "6877",
        "decimals": 2
      },
      "commissions_and_charges": {
        "currency": "EUR",
        "value": "1128",
        "decimals": 2
      }
    },
    "price_breakdown": [
      {
        "room_reservation_id": "5214001415",
        "charges": [
          {
            "type": "VAT",
            "amount": {
              "currency": "EUR",
              "value": "389",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "TRUE"
          },
          {
            "type": "City tax",
            "amount": {
              "currency": "EUR",
              "value": "6",
              "decimals": 0
            },
            "is_already_collected_from_guest": "FALSE",
            "is_included_total_partner_payout": "FALSE"
          },
          {
            "type": "COMMISSION",
            "amount": {
              "currency": "EUR",
              "value": "1032",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "FALSE"
          }
        ]
      }
    ]
  },
  "errors": [],
  "warnings": []
}

Response body elements

The following table describes the response elements:

Element	Description	Type
`data`	Contains the response data.	object
: `reservation_id`	Specifies the identifier of the reservation.	string
: `property_id`	Specifies the identifier of the property.	string
: `payout_type`	Specifies the type of payout: `GROSS`, `NET`, or `UNKNOWN`.	string
: `total_price_of_reservation`	Contains information on the total cost of the reservation for the guest.	object
: `total_amount_paid`	Contains information on the total amount the guest paid to Booking.com.	object
::: `value`	Amount paid.	string
::: `currency`	Currency of the amount.	string
::: `decimals`	Number of decimals in the amount.	string
:: `total_amount_to_collect_at_property`	Contains information on the estimated amount the partner needs to collect from the guest at checkin.	object
::: `value`	Amount to be collected.	string
::: `currency`	Currency of the amount.	string
::: `decimals`	Number of decimals in the amount.	string
: `partner_payout`	Contains information on what Booking.com has to pay out to the partner.	object
:: `total_payout`	Contains information on the total amount that will be paid to the partner.	object
::: `value`	Payout amount.	integer
::: `currency`	Currency of the amount.	string
::: `decimals`	Number of decimals in the amount.	string
:: `commissionable_price`	Contains information on the total commissionable price.	object
::: `value`	Price amount.	string
::: `currency`	Currency of the amount.	string
::: `decimals`	Number of decimals in the amount.	string
:: `commission_and_charges`	Contains information on the total amount of commission and other charges such as fees.	object
::: `value`	Amount of the commission and other charges.	string
::: `currency`	Currency of the amount.	string
::: `decimals`	Number of decimals in the amount.	string
: `price_breakdown`	Contains a price breakdown for the given reservation, per each room the guest booked.	object
:: `room_reservation_id`	Specifies the identifier of the booked room.	string
:: `charges`	Contains a list of charges applicable to this room.	object
::: `type`	Specifies the type of charge, such as `city_tax`, `resort_fees`, or `internet_fees`.	string
::: `amount`	Contains information on the total amount of all charges.	object
:::: `value`	Total amount of charges.	string
:::: `currency`	Currency of the amount.	string
:::: `decimals`	Number of decimals in the amount.	string
::: `is_already_collected_from_guest`	If set to `TRUE`, it indicates that the charged amount has already been collected from the guest, and the partner doesn't need to collect anything. Otherwise, it's set to `FALSE`, and the partner has to collect the money at checkin. If set to `UNKNOWN`, no information is available. For more, see Explanation of payment flags from response.	enum
::: `is_included_total_partner_payout`	If set to `TRUE`, it indicates that the charged amount is included in the payout and will be transferred to the partner. Otherwise, it's set to `FALSE`, which means the charged amount is intended for another party, such as the government. If set to `UNKNOWN`, no information is available. For more, see Explanation of payment flags from response.	enum
`errors`	Contains potential errors. These can help you understand what went wrong with your request. For more information, see Response codes.	array
`warnings`	Contains potential warnings. These can help you improve your requests.	array

Mapping `room_reservation_id` (B.XML) and `RoomStay IndexNumber` (OTA)

The Payments API gives a detailed price breakdown for a given reservation, but doesn't include any other reservation information. The API takes room_reservation_id as an identifier for each room, but if you're using the Reservations API OTA format, you don't not receive this information as part of your reservation information. This makes it hard to map the price breakdown details with the reservation information.

To get the whole picture, you need to understand the correlation between the room_reservation_id (B.XML) and RoomStay IndexNumber (OTA) fields. The RoomStay IndexNumber is:

Last three digits of room_reservation_id
With leading zeros removed
If last three digits are 000, they're changed to 500

For example, if room_reservation_id is 5430456337, RoomStay IndexNumber is 337.

Getting BT payout details for reservation

GET https://payments-api.booking.com/connectivity-payments/reservations/{reservation-id}/payout/bt

The GET /connectivity-payments/reservations/{reservation-id}/payout/bt request enables you to get information on the bank transfer payout for the respective reservation and any changes to the payout.

If a payout-related update is available, you receive a notification of type BANK_TRANSFER_UPDATE, and then you can query the endpoint to get the details.

Path parameters

The following table describes what elements you must add as path parameters:

Element	Description	Type	Required/Optional
`reservation-id`	Specifies the identifier of the reservation.	string	required

Headers

Element	Description	Type	Required/Optional
`accept-version`	Specifies the version of the API you want to use.	string	optional

Response body example

The following is a successful response body example:

{
  "meta": {
    "ruid": "2"
  },
  "data": {
    "reservation_id": "4482006106",
    "property_id": "367104",
    "payout_type": "NET",
    "payout": {
      "bank_transfers": [
        {
          "amount": {
            "currency": "EUR",
            "value": "5749",
            "decimals": 2
          },
          "status": "PENDING",
          "payout_date": "2024-11-28"
        }
      ]
    }
  },
  "errors": [],
  "warnings": []
}

Response body elements

The following table describes the response elements:

Element	Description	Type
`data`	Contains the response data.	object
: `reservation_id`	Specifies the identifier of the reservation.	string
: `property_id`	Specifies the identifier of the property.	string
: `payout_type`	Specifies the type of payout: `GROSS`, `NET`, or `UNKNOWN`.	string
: `payout`	Contains payout details.	object
:: `bank_transfers`	Contains information on the bank transfer payout.	object
:: `amount`	Contains information on the amount to be transferred.	object
:::: `value`	Payout amount.	string
:::: `currency`	Currency of the amount.	string
:::: `decimals`	Number of decimals in the amount.	string
:: `status`	Specifies the status of the bank transfer payout: `PENDING`, `PAID`, or `UNKNOWN`.	string
:: `payout_date`	Specified the date the amount is to be paid out to the partner. Format: YYYY-MM-DD.	string
`errors`	Contains potential errors. These can help you understand what went wrong with your request. For more information, see Response codes.	array
`warnings`	Contains potential warnings. These can help you improve your requests.	array

Getting VCC payout details for reservation

GET https://payments-api.booking.com/connectivity-payments/reservations/{reservation-id}/payout/vcc?vcc-id={vcc-id}

The GET /connectivity-payments/reservations/{reservation-id}/payout/vcc?vcc-id={vcc-id} request enables you to get information on the virtual credit cards associated with the respective reservation and changes to the VCC payout.

If a payout-related update is available, you receive a notification of type VIRTUAL_CREDIT_CARD_UPDATE, and then you can query the endpoint to get the details.

Path parameters

The following table describes what elements you must add as path parameters:

Element	Description	Type	Required/Optional
`reservation-id`	Specifies the identifier of the reservation.	string	required

Query parameters

The following table describes what elements you must add as query parameters:

Element	Description	Type	Required/Optional
`vcc-id`	Specifies the identifier of the VCC. If provided in the request, information on the given VCC is returned. Otherwise, all VCCs for the reservation are returned,	string	optional

Headers

Element	Description	Type	Required/Optional
`accept-version`	Specifies the version of the API you want to use.	string	optional

Response body example

The following is a successful response body example:

{
  "meta": {
    "ruid": "2"
  },
  "data": {
    "reservation_id": "4349189723",
    "property_id": "246631",
    "payout_type": "GROSS",
    "payout": {
      "virtual_credit_cards": [
        {
          "activation_date": "2024-10-09",
          "id": "7ca61d4e-c905-46eb-ae5e-b384416d6fbb",
          "current_balance": {
            "currency": "EUR",
            "value": "0",
            "decimals": 0
          },
          "expiration_date": "2025-10-10",
          "status": "FULLY_CHARGED",
          "card_details": {
            "cvc": "737",
            "card_name": "Booking.com",
            "card_number": "1234567891234567",
            "card_expiry": "03/30"
          }
        }
      ]
    }
  },
  "errors": [],
  "warnings": []
}

Response body elements

The following table describes the response elements:

Element	Description	Type
`data`	Contains the response data.	object
: `reservation_id`	Specifies the identifier of the reservation.	string
: `property_id`	Specifies the identifier of the property.	string
: `payout_type`	Specifies the type of payout: `GROSS`, `NET`, or `UNKNOWN`.	string
: `payout`	Contains payout details.	object
:: `virtual_credit_cards`	Contains details on the VCC.	object
::: `activation_date`	Specifies the date when the VCC is activated.	string
::: `id`	Specifies the identifier of the VCC.	string
::: `current_balance`	Contains information on the current balance of the VCC.	object
:::: `value`	Amount on the VCC.	string
:::: `currency`	Currency of the amount.	string
:::: `decimals`	Number of decimals in the amount.	string
::: `expiration_date`	Specifies the date when the VCC is deactivated as set by Booking.com. Format: YYYY-MM-DD.	string
:: `status`	Specifies the status of the VCC: `AVAILABLE`, `FUNDED`, `NOT_FUNDED`, `PARTIALLY_CHARGED`, `FULLY_CHARGED`, or `CANCELLED`. For more info, see VCC statuses.	string
::: `card_details`	Contains details on the VCC. Also see Limitations with sharing card details.	object
:::: `cvc`	CVC of the VCC.	string
:::: `card_name`	Name of the VCC.	string
:::: `card_number`	Number of the VCC.	string
:::: `card_type`	Type of the VCC.	string
:::: `card_expiry`	Specifies the date when the VCC gets expired as set by the card issuer. Format: MM/YY.	string
`errors`	Contains potential errors. These can help you understand what went wrong with your request. For more information, see Response codes.	array
`warnings`	Contains potential warnings. These can help you improve your requests. Also see Limitations with sharing card details.	array

VCC statuses

Status	Description
`AVAILABLE`	Card is available but not activated. If the full or partial amount is loaded to the card but this happens before the activation date, the card will still have this status. The status changes to `FUNDED` only at the activation date.
`NOT_LOADED`	Card is activated but the amount is not loaded.
`FUNDED`	Card is activated and the amount is loaded. When the VCC has this status, it can be charged.
`FULLY_CHARGED`	Card is charged completely.
`PARTIALLY_CHARGED`	Card is partially charged.
`CANCELLED`	Card is cancelled or closed.
`UNKNOWN`	Status is unknown.

VCC status lifecycle

AVAILABLE > NOT_LOADED/ FUNDED (based on the amount) > PARTIALLY_CHARGED/FULLY_CHARGED (based on the charge amount) > CANCELLED.

Explanation of payment flags from response

When calling the /reservations/{reservation-id} and /reservations/{reservation-id}/breakdown endpoints, you see a combination of two flags in the response: is_already_collected_from_guest and is_included_total_partner_payout. Depending on whether each flag is set to TRUE or FALSE, together they cover different scenarios:

`is_already_collected_from_guest`	`is_included_total_partner_payout`	Scenario explanation
`FALSE`	`FALSE`	- Fees/taxes were not collected from the guest during the booking process. - Booking.com will not pay out the fees/taxes to the property. - The property needs to collect the fees/taxes from the guest at the check-in. For example, this scenario may apply to city taxes.
`FALSE`	`TRUE`	- Fees/taxes were not collected from the guest during the booking process. - Booking.com will bear the cost of fees/taxes and will pay it out to the property. For example, this scenario applies to Smart Flex reservations where Booking.com has to compensate the partner for a canceled reservation because it didn't find "replacement guests".
`TRUE`	`FALSE`	- Fees/taxes were collected from the guest during the booking process. - Booking.com withheld the fees/taxes and will pay them out directly to the authority, not the property. For example, this scenario may apply to US taxes.
`TRUE`	`TRUE`	- Fees/taxes were collected from the guest during the booking process. - Booking.com will pay out the fees/taxes to the property. For example, this scenario may apply to various property fees and VAT.

Response codes

This table lists and describes the response codes that the Payment Details API can return.

Code	Type	Description
200	Success	Information for the accommodation reservation is fetched successfully.
400	Non-retryable failure	Request payload is invalid.
401	Non-retryable failure	Machine account is not authenticated.
403	Non-retryable failure	Machine account is not authorized to fetch the requested information.
404	Non-retryable failure	Specified reservation doesn't exist.
410	Non-retryable failure	Requested resource is outdated and no longer available to be served.
429	Retryable error	You exceeded the rate limit.
500	Retryable failure	Request failed with an internal server error.

Take into account the following compliance-related limitations concerning the /reservations/{reservation-id} and /reservations/{reservation-id}/payout/vcc?vcc-id={vcc-id} endpoints.

According to the policy, we might be unable to share card details with you when you're calling either of the endpoints mentioned above. In this case, the response you receive contains a warning message, and all the fields within the card_details property are null.

There are two types of warning messages:

If fetching the card details failed: “Sorry, could not fetch card details at the moment. Please try again later”.
If card details cannot be shared at the moment due to security reasons: “Virtual Credit Card details cannot be shared for this reservation”.

Example response:

{
  "meta": null,
  "data": {
    "reservation_id": "4970243170",
    "property_id": "6408656",
    "payout_type": "GROSS",
    "payout": {
      "virtual_credit_cards": [
        {
          "activation_date": "2024-07-03",
          "id": "2496692317",
          "current_balance": {
            "value": 0,
            "currency": "EUR"
            "decimals": 0
          },
          "expiration_date": "2025-07-03",
          "status": "NOT_LOADED",
          "card_details": {
            "cvc": null,
            "card_name": null,
            "card_number": null,
            "card_expiry": null
          }
        }
      ]
    }
  },
  "errors": null,
  "warnings": [
    { "message": "Sorry, could not fetch card details at the moment. Please try again later" }
  ]
}

Managing payment and payout details

Quick actions

Getting payout details for reservation

Path parameters

Headers

Response body example

Response body elements

Getting price breakdown for reservation

Path parameters

Headers

Response body example

Response body elements

Mapping room_reservation_id (B.XML) and RoomStay IndexNumber (OTA)

Getting BT payout details for reservation

Path parameters

Headers

Response body example

Response body elements

Getting VCC payout details for reservation

Path parameters

Query parameters

Headers

Response body example

Response body elements

VCC statuses

VCC status lifecycle

Explanation of payment flags from response

Response codes

Limitations with sharing card details

Mapping `room_reservation_id` (B.XML) and `RoomStay IndexNumber` (OTA)