# 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-payout-details-for-reservation)
* [Getting price breakdown for reservation](#getting-price-breakdown-for-reservation)
* [Getting VCC payout details for reservation](#getting-vcc-payout-details-for-reservation)
* [Getting BT payout details for reservation](#getting-bt-payout-details-for-reservation)


## Getting payout details for reservation


```http
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. Defaults to the latest version (currently 1.1). To keep the v1.0 behavior, pass `1.0`. | string | optional |


Every successful response includes the `api-response` HTTP header indicating the API version that served the request, regardless of whether you explicitly sent the `accept-version` request header. If you don't specify the `accept-version` request header, the latest version of the API is used by default.

### Response body example

v1.1 response
The following is a successful v1.1 response body example:


```json
{
  "meta": {
    "ruid": "6ca61d4e-c805-46eb-ae5e-b384416d6faa"
  },
  "data": {
    "reservation_id": "4482006106",
    "property_id": "367104",
    "payout_type": "NET",
    "payment_tags": [
      "PAYMENTS_BY_BOOKING"
    ],
    "payout_status": "PAID",
    "total_price_of_reservation": {
      "total_amount_paid": {
        "currency": "EUR",
        "value": "12000",
        "decimals": 2
      },
      "total_amount_to_collect_at_property": {
        "currency": "EUR",
        "value": "500",
        "decimals": 2
      }
    },
    "partner_payout": {
      "total_payout": {
        "currency": "EUR",
        "value": "9874",
        "decimals": 2
      },
      "commissionable_price": {
        "currency": "EUR",
        "value": "12000",
        "decimals": 2
      },
      "commissions_and_charges": {
        "currency": "EUR",
        "value": "2000",
        "decimals": 2,
        "breakdown": {
          "total_commissions": {
            "currency": "EUR",
            "value": "1800",
            "decimals": 2
          },
          "total_charges": {
            "currency": "EUR",
            "value": "200",
            "decimals": 2
          }
        }
      }
    },
    "payout": {
      "bank_transfers": [
        {
          "amount": {
            "currency": "EUR",
            "value": "5749",
            "decimals": 2
          },
          "status": "PAID",
          "payout_date": "2024-11-28",
          "bank_transfer_reference": "2Njwiz4L8Qob3Mox"
        }
      ],
      "virtual_credit_cards": [],
      "customer_credit_cards": []
    },
    "price_breakdown": [
      {
        "room_reservation_id": "5214001415",
        "charges": [
          {
            "type": "VAT",
            "amount": {
              "currency": "EUR",
              "value": "1000",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "TRUE",
            "applicable_rate": {
              "type": "PERCENTAGE",
              "value": "10",
              "decimals": 0
            },
            "applicable_type": null
          },
          {
            "type": "City tax",
            "amount": {
              "currency": "EUR",
              "value": "500",
              "decimals": 2
            },
            "is_already_collected_from_guest": "FALSE",
            "is_included_total_partner_payout": "FALSE",
            "applicable_rate": {
              "type": "PERCENTAGE",
              "value": "5",
              "decimals": 0
            },
            "applicable_type": null
          },
          {
            "type": "Cleaning Fee",
            "amount": {
              "currency": "EUR",
              "value": "1500",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "TRUE",
            "applicable_rate": null,
            "applicable_type": [
              "PER_PERSON"
            ]
          },
          {
            "type": "COMMISSION",
            "amount": {
              "currency": "EUR",
              "value": "1800",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "FALSE",
            "applicable_rate": null,
            "applicable_type": null
          },
          {
            "type": "Short Stay Levy (Withheld Tax)",
            "amount": {
              "currency": "EUR",
              "value": "126",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "FALSE",
            "applicable_rate": null,
            "applicable_type": null
          },
          {
            "type": "PAYMENT CHARGE",
            "amount": {
              "currency": "EUR",
              "value": "200",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "FALSE",
            "applicable_rate": null,
            "applicable_type": null
          }
        ]
      }
    ]
  },
  "errors": [],
  "warnings": []
}
```

v1.0 response
The following is a successful v1.0 response body example:


```json
{
  "meta": {
    "ruid": "a5b1d72a-31ef-4dca-922f-bf94abeebb46"
  },
  "data": {
    "reservation_id": "4482006106",
    "property_id": "367104",
    "payout_type": "NET",
    "payout_status": "PAID",
    "total_price_of_reservation": {
      "total_amount_paid": {
        "currency": "EUR",
        "value": "12000",
        "decimals": 2
      },
      "total_amount_to_collect_at_property": {
        "currency": "EUR",
        "value": "500",
        "decimals": 2
      }
    },
    "partner_payout": {
      "total_payout": {
        "currency": "EUR",
        "value": "10074",
        "decimals": 2
      },
      "commissionable_price": {
        "currency": "EUR",
        "value": "12000",
        "decimals": 2
      },
      "commissions_and_charges": {
        "currency": "EUR",
        "value": "1800",
        "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": "1000",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "TRUE"
          },
          {
            "type": "City tax",
            "amount": {
              "currency": "EUR",
              "value": "500",
              "decimals": 2
            },
            "is_already_collected_from_guest": "FALSE",
            "is_included_total_partner_payout": "FALSE"
          },
          {
            "type": "COMMISSION",
            "amount": {
              "currency": "EUR",
              "value": "1800",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "FALSE"
          },
          {
            "type": "Short Stay Levy (Withheld Tax)",
            "amount": {
              "currency": "EUR",
              "value": "126",
              "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 **for the latest version** (currently v1.1):

| 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 |
| **:** `payment_tags` | Specifies the payment type and collection method for a reservation. For example, `PAYMENTS_BY_BOOKING`. | 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 |
| **::** `total_payout` | Contains information on the **estimated** 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, with a breakdown. A payment charge for the cancellable/"Pay later" reservations (which is part of commissions and charges) will be available no later than the check-in date. | object |
| **:::** `value` | Total amount of the commission and other charges. | string |
| **:::** `currency` | Currency of the amount. | string |
| **:::** `decimals` | Number of decimals in the total amount. | string |
| **:::** `breakdown` | Contains the breakdown of the commissions and charges amount. | object |
| **::::** `total_commissions` | Contains information on the total amount of commissions. | object |
| **:::::** `currency` | Currency of the amount. | string |
| **:::::** `value` | Commission amount. | string |
| **:::::** `decimals` | Number of decimals in the amount. | string |
| **::::** `total_charges` | Contains information on the total amount of charges. | object |
| **:::::** `currency` | Currency of the amount. | string |
| **:::::** `value` | Charges amount. | string |
| **:::::** `decimals` | Number of decimals in the 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`. While the status is `PENDING`, we show the estimated `amount` and `payout_date`, not the exact ones. | string |
| **:::** `payout_date` | Specifies the date the amount is to be paid out to the partner. Format: YYYY-MM-DD. | string |
| **:::** `bank_transfer_reference` | Specifies the identifier of the bank transfer payout. | string |
| **::** `customer_credit_cards` | Reserved for future Payments API updates. | object |
| **::** `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](#vcc-statuses). | string |
| **:::** `card_details` | Contains details of the VCC. Also see [Limitations with sharing card details](#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` | The value of this field is dynamic. It specifies the type of charge, such as `VAT`, `City tax`, `Cleaning fee`, `Bed linens fee`, `COMMISSION`, `PAYMENT CHARGE`, `Short Stay Levy (Withheld Tax)`, including country-specific taxes (e.g. for Malaysia and [Canada](https://partner.booking.com/en-us/help/commission-invoices-tax/local-taxes/understanding-tax-remittance-management-canada) as of November 2025). | string |
| **:::** `amount` | Contains information on the total charge. | object |
| **::::** `value` | Total value of the charge. | 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](#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](#explanation-of-payment-flags-from-response). | enum |
| **:::** `applicable_rate` | Contains information on the applicable base rate used to calculate the charge. If no applicable rate is available, the response returns `null` for this field. | object |
| **::::** `type` | The value of this field is dynamic. It specifies the calculation method used for the base rate. For example, `PERCENTAGE`. | string |
| **::::** `value` | Base rate value. | string |
| **::::** `decimals` | Number of decimals in the base rate. | string |
| **:::** `applicable_type` | The value of this field is dynamic. It specifies the calculation method used for the base rate. For example, `PERCENTAGE`. It contains information on how the charge is applied to the reservation. For example, `PER_PERSON` or `PER_NIGHT`. If the information is not available, the response returns `null` for this field. | string |
| `errors` | Contains potential errors. These can help you understand what went wrong with your request. For more information, see [Response codes](#response-codes). | array |
| `warnings` | Contains potential warnings. These can help you improve your requests. Also see [Limitations with sharing card details](#limitations-with-sharing-card-details). | array |


## Getting price breakdown for reservation


```http
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. Defaults to the latest version (currently 1.1). To keep the v1.0 behavior, pass `1.0`. | string | optional |


Every successful response includes the `api-response` HTTP header indicating the API version that served the request, regardless of whether you explicitly sent the `accept-version` request header. If you don't specify the `accept-version` request header, the latest version of the API is used by default.

### Response body example

v1.1 response
The following is a successful v1.1 response body example:


```json
{
    "meta": {
        "ruid": "6ca61d4e-c805-46eb-ae5e-b384416d6faa"
    },
    "data": {
        "reservation_id": 4482006106,
        "property_id": 367104,
        "payout_type": "NET",
        "payment_tags": [
            "PAYMENTS_BY_BOOKING"
        ],
        "total_price_of_reservation": {
            "total_amount_paid": {
                "currency": "EUR",
                "value": 12000,
                "decimals": 2
            },
            "total_amount_to_collect_at_property": {
                "currency": "EUR",
                "value": 500,
                "decimals": 2
            }
        },
        "partner_payout": {
            "total_payout": {
                "currency": "EUR",
                "value": 9874,
                "decimals": 2
            },
            "commissionable_price": {
                "currency": "EUR",
                "value": 12000,
                "decimals": 2
            },
            "commissions_and_charges": {
                "currency": "EUR",
                "value": 2000,
                "decimals": 2,
                "breakdown": {
                    "total_commissions": {
                        "currency": "EUR",
                        "value": 1800,
                        "decimals": 2
                    },
                    "total_charges": {
                        "currency": "EUR",
                        "value": 200,
                        "decimals": 2
                    }
                }
            }
        },
        "price_breakdown": [
            {
                "room_reservation_id": 5214001415,
                "charges": [
                    {
                        "type": "VAT",
                        "amount": {
                            "currency": "EUR",
                            "value": 1000,
                            "decimals": 2
                        },
                        "is_already_collected_from_guest": "TRUE",
                        "is_included_total_partner_payout": "TRUE",
                        "applicable_rate": {
                            "type": "PERCENTAGE",
                            "value": 10,
                            "decimals": 0
                        },
                        "applicable_type": null
                    },
                    {
                        "type": "City tax",
                        "amount": {
                            "currency": "EUR",
                            "value": 500,
                            "decimals": 2
                        },
                        "is_already_collected_from_guest": "FALSE",
                        "is_included_total_partner_payout": "FALSE",
                        "applicable_rate": {
                            "type": "PERCENTAGE",
                            "value": 5,
                            "decimals": 0
                        },
                        "applicable_type": null
                    },
                    {
                        "type": "Cleaning Fee",
                        "amount": {
                            "currency": "EUR",
                            "value": 1500,
                            "decimals": 2
                        },
                        "is_already_collected_from_guest": "TRUE",
                        "is_included_total_partner_payout": "TRUE",
                        "applicable_rate": null,
                        "applicable_type": [
                            "PER_PERSON"
                        ]
                    },
                    {
                        "type": "COMMISSION",
                        "amount": {
                            "currency": "EUR",
                            "value": 1800,
                            "decimals": 2
                        },
                        "is_already_collected_from_guest": "TRUE",
                        "is_included_total_partner_payout": "FALSE",
                        "applicable_rate": null,
                        "applicable_type": null
                    },
                    {
                        "type": "Short Stay Levy (Withheld Tax)",
                        "amount": {
                            "currency": "EUR",
                            "value": 126,
                            "decimals": 2
                        },
                        "is_already_collected_from_guest": "TRUE",
                        "is_included_total_partner_payout": "FALSE",
                        "applicable_rate": null,
                        "applicable_type": null
                    },
                    {
                        "type": "PAYMENT CHARGE",
                        "amount": {
                            "currency": "EUR",
                            "value": 200,
                            "decimals": 2
                        },
                        "is_already_collected_from_guest": "TRUE",
                        "is_included_total_partner_payout": "FALSE",
                        "applicable_rate": null,
                        "applicable_type": null
                    }
                ]
            }
        ]
    },
    "errors": [],
    "warnings": []
}
```

v1.0 response
The following is a successful v1.0 response body example:


```json
{
  "meta": {
    "ruid": "a5b1d72a-31ef-4dca-922f-bf94abeebb46"
  },
  "data": {
    "reservation_id": "4482006106",
    "property_id": "367104",
    "payout_type": "NET",
    "total_price_of_reservation": {
      "total_amount_paid": {
        "currency": "EUR",
        "value": "12000",
        "decimals": 2
      },
      "total_amount_to_collect_at_property": {
        "currency": "EUR",
        "value": "500",
        "decimals": 2
      }
    },
    "partner_payout": {
      "total_payout": {
        "currency": "EUR",
        "value": "10074",
        "decimals": 2
      },
      "commissionable_price": {
        "currency": "EUR",
        "value": "12000",
        "decimals": 2
      },
      "commissions_and_charges": {
        "currency": "EUR",
        "value": "1800",
        "decimals": 2
      }
    },
    "price_breakdown": [
      {
        "room_reservation_id": "5214001415",
        "charges": [
          {
            "type": "VAT",
            "amount": {
              "currency": "EUR",
              "value": "1000",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "TRUE"
          },
          {
            "type": "City tax",
            "amount": {
              "currency": "EUR",
              "value": "500",
              "decimals": 2
            },
            "is_already_collected_from_guest": "FALSE",
            "is_included_total_partner_payout": "FALSE"
          },
          {
            "type": "COMMISSION",
            "amount": {
              "currency": "EUR",
              "value": "1800",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "FALSE"
          },
          {
            "type": "Short Stay Levy (Withheld Tax)",
            "amount": {
              "currency": "EUR",
              "value": "126",
              "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 **for the latest version** (currently v1.1):

| 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 |
| **:** `payment_tags` | Specifies the payment type and collection method for a reservation. For example, `PAYMENTS_BY_BOOKING`. | 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 **estimated** 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 |
| **::** `commissions_and_charges` | Contains information on the total amount of commission and other charges, with a breakdown. A payment charge for the cancellable/"Pay later" reservations (which is part of commissions and charges) will be available no later than the check-in date. | object |
| **:::** `value` | Amount of the commission and other charges. | string |
| **:::** `currency` | Currency of the amount. | string |
| **:::** `decimals` | Number of decimals in the amount. | string |
| **:::** `breakdown` | Contains the breakdown of the commissions and charges amount. | object |
| **::::** `total_commissions` | Contains information on the total amount of commissions. | object |
| **:::::** `currency` | Currency of the amount. | string |
| **:::::** `value` | Commission amount. | string |
| **:::::** `decimals` | Number of decimals in the amount. | string |
| **::::** `total_charges` | Contains information on the total amount of charges. | object |
| **:::::** `currency` | Currency of the amount. | string |
| **:::::** `value` | Charges 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` | The value of this field is dynamic. It specifies the type of charge, such as `VAT`, `City tax`, `Cleaning fee`, `Bed linens fee`, `COMMISSION`, `PAYMENT CHARGE`, `Short Stay Levy (Withheld Tax)`, including country-specific taxes (e.g. for Malaysia and [Canada](https://partner.booking.com/en-us/help/commission-invoices-tax/local-taxes/understanding-tax-remittance-management-canada) as of November 2025). | string |
| **:::** `amount` | Contains information on the total charge. | object |
| **::::** `value` | Total value of the charge. | 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](#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](#explanation-of-payment-flags-from-response). | enum |
| **:::** `applicable_rate` | Contains information on the applicable base rate used to calculate the charge. If no applicable rate is available, the response returns `null` for this field. | object |
| **::::** `type` | The value of this field is dynamic. It specifies the calculation method used for the base rate. For example, `PERCENTAGE`. | string |
| **::::** `value` | Base rate value. | string |
| **::::** `decimals` | Number of decimals in the base rate. | string |
| **:::** `applicable_type` | The value of this field is dynamic. It specifies the calculation method used for the base rate. For example, `PERCENTAGE`. It contains information on how the charge is applied to the reservation. For example, `PER_PERSON` or `PER_NIGHT`. If the information is not available, the response returns `null` for this field. | string |
| `errors` | Contains potential errors. These can help you understand what went wrong with your request. For more information, see [Response codes](#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


```http
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. Defaults to the latest version (currently 1.1). To keep the v1.0 behavior, pass `1.0`. | string | optional |


Every successful response includes the `api-response` HTTP header indicating the API version that served the request, regardless of whether you explicitly sent the `accept-version` request header. If you don't specify the `accept-version` request header, the latest version of the API is used by default.

### Response body example

v1.1 response
The following is a successful v1.1 response body example:


```json
{
  "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",
          "bank_transfer_reference":"2Njwiz4L8Qob3Mox"
        }
      ]
    }
  },
  "errors": [],
  "warnings": []
}
```

v1.0 response
The following is a successful v1.0 response body example:


```json
{
  "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 **for the latest version** (currently v1.1):

| 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`. While the status is `PENDING`, we show the estimated `amount` and `payout_date`, not the exact ones. | string |
| **:::** `payout_date` | Specifies the date the amount is to be paid out to the partner. Format: YYYY-MM-DD. | string |
| **:::** `bank_transfer_reference` | Specifies the identifier of the bank transfer payout. | string |
| `errors` | Contains potential errors. These can help you understand what went wrong with your request. For more information, see [Response codes](#response-codes). | array |
| `warnings` | Contains potential warnings. These can help you improve your requests. | array |


## Getting VCC payout details for reservation


```http
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. Defaults to the latest version (currently 1.1). To keep the v1.0 behavior, pass `1.0`. | string | optional |


Every successful response includes the `api-response` HTTP header indicating the API version that served the request, regardless of whether you explicitly sent the `accept-version` request header. If you don't specify the `accept-version` request header, the latest version of the API is used by default.

### Response body example

v1.1 response
The following is a successful v1.1 response body example:


```json
{
  "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": []
}
```

v1.0 response
The following is a successful v1.0 response body example:


```json
{
  "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 **for the latest version** (currently v1.1):

| 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 |
| **::** `customer_credit_cards` | Reserved for future Payments API updates. | 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](#vcc-statuses). | string |
| **:::** `card_details` | Contains details on the VCC. Also see [Limitations with sharing card details](#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](#response-codes). | array |
| `warnings` | Contains potential warnings. These can help you improve your requests. Also see [Limitations with sharing card details](#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. |


In select markets, Booking.com collects per person charges (such as city tax) from guests during the booking process. When this happens, `is_already_collected_from_guest` changes from `FALSE` to `TRUE`. For more details and payload examples, see [Understanding per person charges collection](/connectivity/docs/payments-api/per-person-charges-collection).

## 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. |


## Limitations with sharing card details

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" }
  ]
}
```