Last updated

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

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:

ElementDescriptionTypeRequired/Optional
reservation-idSpecifies the identifier of the reservation.stringrequired

Headers

ElementDescriptionTypeRequired/Optional
accept-versionSpecifies the version of the API you want to use.stringoptional

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:

ElementDescriptionType
dataContains the response data.object
: reservation_idSpecifies the identifier of the reservation.string
: property_idSpecifies the identifier of the property.string
: payout_typeSpecifies the type of payout: GROSS, NET, or UNKNOWN.string
:: payout_statusSpecifies the status of the payout: PENDING, PAID, PARTIALLY_PAID, CANCELLED, or UNKNOWN.string
: total_price_of_reservationContains information on the total cost of the reservation for the guest.object
:: total_amount_paidContains information on the total amount the guest paid to Booking.com.object
::: valueCost amount.string
::: currencyCurrency of the amount.string
::: decimalsNumber of decimals in the amount.string
:: total_amount_to_collect_at_propertyContains information on the estimated amount the partner needs to collect from the guest at checkin.object
::: valueAmount to be collected.string
::: currencyCurrency in which the amount is to be collected.string
::: decimalsNumber of decimals in the amount.string
: partner_payoutContains information on what Booking.com has to pay out to the partner.object
:: total_payoutContains information on the total amount that will be paid to the partner.object
::: valuePayout amount.string
::: currencyCurrency of the amount.string
::: decimalsNumber of decimals in the amount.string
:: commissionable_priceContains information on the total commissionable price.object
::: valuePrice amount.string
::: currencyCurrency of the price.string
::: decimalsNumber of decimals in the amount.string
:: commissions_and_chargesContains information on the total amount of commission and other charges such as fees.object
::: valueAmount of the commission and other charges.string
::: currencyCurrency of the amount.string
::: decimalsNumber of decimals in the total amount.string
: payoutContains payout details.object
:: bank_transfersContains information on the bank transfer payout to be transferred.object
:: amountContains information on the bank transfer payout amount.object
:::: valuePayout amount.string
:::: currencyCurrency of the amount.string
:::: decimalsNumber of decimals in the amount.string
:: statusSpecifies the status of the bank transfer payout: PENDING, PAID, or UNKNOWN.string
:: payout_dateSpecified the date the amount is to be paid out to the partner. Format: YYYY-MM-DD.string
: virtual_credit_cardsContains details on the VCCs.object
:: idSpecifies the identifier of the VCC.string
:: activation_dateSpecifies the date when the VCC is activated.string
:: current_balanceContains information on the current balance of the VCC.object
::: valueAmount on the VCC.string
::: currencyCurrency of the amount.string
::: decimalsNumber of decimals in the amount.string
:: expiration_dateSpecifies the date when the VCC gets expired as set by Booking.com. Format: YYYY-MM-DD.string
:: statusSpecifies the status of the VCC: NOT_LOADED, FUNDED, CANCELLED, AVAILABLE, FULLY_CHARGED, PARTIALLY_CHARGED, or UNKNOWN. For more info, see VCC statuses.string
:: card_detailsContains details of the VCC. Also see Limitations with sharing card details.object
::: cvcCVC of the VCC.string
::: card_nameName of the VCC.string
::: card_typeType of the VCC.string
::: card_numberNumber of the VCC.string
:: card_expirySpecifies the date when the VCC gets expired as set by the card issuer. Format: MM/YY.string
: price_breakdownContains a price breakdown for the given reservation, per each room the guest booked.object
:: room_reservation_idSpecifies the identifier of the booked room.string
:: chargesContains a list of charges applicable to this room.object
::: typeSpecifies the type of charge, such as city_tax, resort_fees, or internet_fees.string
::: amountContains information on the total amount of all charges.object
:::: valueTotal amount of charges.string
:::: currencyCurrency of the amount.string
:::: decimalsNumber of decimals in the amount.string
::: is_already_collected_from_guestIf 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_payoutIf 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
errorsContains potential errors. These can help you understand what went wrong with your request. For more information, see Response codes.array
warningsContains 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:

ElementDescriptionTypeRequired/Optional
reservation-idSpecifies the identifier of the reservation.stringrequired

Headers

ElementDescriptionTypeRequired/Optional
accept-versionSpecifies the version of the API you want to use.stringoptional

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:

ElementDescriptionType
dataContains the response data.object
: reservation_idSpecifies the identifier of the reservation.string
: property_idSpecifies the identifier of the property.string
: payout_typeSpecifies the type of payout: GROSS, NET, or UNKNOWN.string
: total_price_of_reservationContains information on the total cost of the reservation for the guest.object
: total_amount_paidContains information on the total amount the guest paid to Booking.com.object
::: valueAmount paid.string
::: currencyCurrency of the amount.string
::: decimalsNumber of decimals in the amount.string
:: total_amount_to_collect_at_propertyContains information on the estimated amount the partner needs to collect from the guest at checkin.object
::: valueAmount to be collected.string
::: currencyCurrency of the amount.string
::: decimalsNumber of decimals in the amount.string
: partner_payoutContains information on what Booking.com has to pay out to the partner.object
:: total_payoutContains information on the total amount that will be paid to the partner.object
::: valuePayout amount.integer
::: currencyCurrency of the amount.string
::: decimalsNumber of decimals in the amount.string
:: commissionable_priceContains information on the total commissionable price.object
::: valuePrice amount.string
::: currencyCurrency of the amount.string
::: decimalsNumber of decimals in the amount.string
:: commission_and_chargesContains information on the total amount of commission and other charges such as fees.object
::: valueAmount of the commission and other charges.string
::: currencyCurrency of the amount.string
::: decimalsNumber of decimals in the amount.string
: price_breakdownContains a price breakdown for the given reservation, per each room the guest booked.object
:: room_reservation_idSpecifies the identifier of the booked room.string
:: chargesContains a list of charges applicable to this room.object
::: typeSpecifies the type of charge, such as city_tax, resort_fees, or internet_fees.string
::: amountContains information on the total amount of all charges.object
:::: valueTotal amount of charges.string
:::: currencyCurrency of the amount.string
:::: decimalsNumber of decimals in the amount.string
::: is_already_collected_from_guestIf 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_payoutIf 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
errorsContains potential errors. These can help you understand what went wrong with your request. For more information, see Response codes.array
warningsContains 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:

ElementDescriptionTypeRequired/Optional
reservation-idSpecifies the identifier of the reservation.stringrequired

Headers

ElementDescriptionTypeRequired/Optional
accept-versionSpecifies the version of the API you want to use.stringoptional

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:

ElementDescriptionType
dataContains the response data.object
: reservation_idSpecifies the identifier of the reservation.string
: property_idSpecifies the identifier of the property.string
: payout_typeSpecifies the type of payout: GROSS, NET, or UNKNOWN.string
: payoutContains payout details.object
:: bank_transfersContains information on the bank transfer payout.object
:: amountContains information on the amount to be transferred.object
:::: valuePayout amount.string
:::: currencyCurrency of the amount.string
:::: decimalsNumber of decimals in the amount.string
:: statusSpecifies the status of the bank transfer payout: PENDING, PAID, or UNKNOWN.string
:: payout_dateSpecified the date the amount is to be paid out to the partner. Format: YYYY-MM-DD.string
errorsContains potential errors. These can help you understand what went wrong with your request. For more information, see Response codes.array
warningsContains 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:

ElementDescriptionTypeRequired/Optional
reservation-idSpecifies the identifier of the reservation.stringrequired

Query parameters

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

ElementDescriptionTypeRequired/Optional
vcc-idSpecifies 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,stringoptional

Headers

ElementDescriptionTypeRequired/Optional
accept-versionSpecifies the version of the API you want to use.stringoptional

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:

ElementDescriptionType
dataContains the response data.object
: reservation_idSpecifies the identifier of the reservation.string
: property_idSpecifies the identifier of the property.string
: payout_typeSpecifies the type of payout: GROSS, NET, or UNKNOWN.string
: payoutContains payout details.object
:: virtual_credit_cardsContains details on the VCC.object
::: activation_dateSpecifies the date when the VCC is activated.string
::: idSpecifies the identifier of the VCC.string
::: current_balanceContains information on the current balance of the VCC.object
:::: valueAmount on the VCC.string
:::: currencyCurrency of the amount.string
:::: decimalsNumber of decimals in the amount.string
::: expiration_dateSpecifies the date when the VCC is deactivated as set by Booking.com. Format: YYYY-MM-DD.string
:: statusSpecifies the status of the VCC: AVAILABLE, FUNDED, NOT_FUNDED, PARTIALLY_CHARGED, FULLY_CHARGED, or CANCELLED. For more info, see VCC statuses.string
::: card_detailsContains details on the VCC. Also see Limitations with sharing card details.object
:::: cvcCVC of the VCC.string
:::: card_nameName of the VCC.string
:::: card_numberNumber of the VCC.string
:::: card_typeType of the VCC.string
:::: card_expirySpecifies the date when the VCC gets expired as set by the card issuer. Format: MM/YY.string
errorsContains potential errors. These can help you understand what went wrong with your request. For more information, see Response codes.array
warningsContains potential warnings. These can help you improve your requests. Also see Limitations with sharing card details.array

VCC statuses

StatusDescription
AVAILABLECard 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_LOADEDCard is activated but the amount is not loaded.
FUNDEDCard is activated and the amount is loaded. When the VCC has this status, it can be charged.
FULLY_CHARGED Card is charged completely.
PARTIALLY_CHARGEDCard is partially charged.
CANCELLEDCard is cancelled or closed.
UNKNOWNStatus 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_guestis_included_total_partner_payoutScenario explanation
FALSEFALSE- 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.
FALSETRUE- 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".
TRUEFALSE- 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.
TRUETRUE- 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.

CodeTypeDescription
200SuccessInformation for the accommodation reservation is fetched successfully.
400Non-retryable failureRequest payload is invalid.
401Non-retryable failureMachine account is not authenticated.
403Non-retryable failureMachine account is not authorized to fetch the requested information.
404Non-retryable failureSpecified reservation doesn't exist.
410Non-retryable failureRequested resource is outdated and no longer available to be served.
429Retryable errorYou exceeded the rate limit.
500Retryable failureRequest 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" }
  ]
}