Booking.com Reservation payout details API

openapi: 3.2.0
info:
  title: Payments Reservation payout details API
  description: Retrieve payment and payout details for accommodation reservations, including partner payout information, breakdowns, bank transfer details, and VCC management.
  contact:
    name: Connectivity Team
    url: https://connect.booking.com
    email: connectivity@booking.com
  version: '1.0'
servers:
- url: https://payments-api.booking.com/
  description: Test using live endpoint
tags:
- name: Reservation payout details
  description: Retrieve detailed partner payout information for accommodation reservations.
paths:
  /connectivity-payments/reservations/{reservation-id}:
    get:
      tags:
      - Reservation payout details
      summary: Get payout details for a reservation
      description: Retrieve payout details for a reservation, including the estimated amount to be collected at the property, payout status and amount, commissions and charges, VCC or bank transfer payout details, and price breakdown.
      operationId: getPayoutDetails
      parameters:
      - name: reservation-id
        in: path
        description: The unique identifier of the reservation.
        required: true
        schema:
          type: integer
      - name: accept-version
        in: header
        description: API version to use.
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer token for authentication.
        required: true
        schema:
          type: string
        example: Bearer <your_token>
      responses:
        '200':
          description: Successfully retrieved payout details including the estimated amount to be collected at the property, payout status and amount, commissions and charges, VCC or bank transfer payout details, and price breakdown.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutDetailsResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '401':
          description: Unauthorized. Missing or invalid authentication token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidTokenResponse'
        '403':
          description: Access Denied!
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedRequestResponse'
        '404':
          description: The reservation data is not found at this moment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationDataNotFoundErrorResponse'
        '410':
          description: Reservation cannot be processed because the checkout date is older than the allowed 18-months window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutDateTooOldErrorResponse'
        '429':
          description: You exceeded the rate limit.
        '500':
          description: The request failed with an internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
components:
  schemas:
    Warning:
      type: object
      description: Warning information
      properties:
        message:
          type: string
          description: Warning message
          example: string
    AmountCommissionsAndCharges:
      description: Contains information on the total amount of commissions and other charges such as fees.
      properties:
        currency:
          type: string
          description: Currency of the amount.
        value:
          type: string
          description: Total amount of commissions and other charges.
        decimals:
          type: integer
          format: int32
          description: Number of decimals in the amount.
        breakdown:
          type: object
          description: Breakdown of commissions and charges.
          properties:
            total_commissions:
              type: object
              description: Total commission amount.
              properties:
                currency:
                  type: string
                  description: Currency of the amount.
                value:
                  type: string
                  description: Total commission amount.
                decimals:
                  type: integer
                  format: int32
                  description: Number of decimals in the amount.
            total_charges:
              type: object
              description: Total charges amount.
              properties:
                currency:
                  type: string
                  description: Currency of the amount.
                value:
                  type: string
                  description: Total charges amount.
                decimals:
                  type: integer
                  format: int32
                  description: Number of decimals in the amount.
    AmountCommissionable:
      description: Contains information on the total commissionable price.
      properties:
        currency:
          type: string
          description: Currency of the amount.
        value:
          type: string
          description: Total commissionable price.
        decimals:
          type: integer
          format: int32
          description: Number of decimals in the amount.
    AmountPaid:
      description: Contains information on the total amount the guest paid to Booking.com.
      properties:
        currency:
          type: string
          description: Currency of the amount.
        value:
          type: string
          description: Amount paid by the guest.
        decimals:
          type: integer
          format: int32
          description: Number of decimals in the amount.
    CheckoutDateTooOldErrorResponse:
      type: object
      description: Response when the checkout date is older than the allowed 18-months window
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
          description: The meta
        data:
          type: object
          description: Data containing required information
        errors:
          type: array
          description: List of errors for the response
          items:
            $ref: '#/components/schemas/Error'
        warnings:
          type: array
          description: List of warnings for the response
          items:
            $ref: '#/components/schemas/Warning'
    UnauthorizedRequestResponse:
      type: object
      description: Response when the token is valid but does not have access to the requested resource.
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
          description: The meta
        data:
          type: object
          description: Data containing required information
        errors:
          type: array
          description: List of errors for the response
          items:
            $ref: '#/components/schemas/Error'
        warnings:
          type: array
          description: List of warnings for the response
          items:
            $ref: '#/components/schemas/Warning'
    Error:
      type: object
      description: Error response containing details about the error
      properties:
        description:
          type: string
          description: Description of the error
        message:
          type: string
          description: Error message
        status_code:
          type: integer
          format: int32
          description: HTTP status code for the error
    DefaultMeta:
      type: object
      description: Metadata for the response
      properties:
        ruid:
          type: string
          description: Request unique identifier
          example: string
    PayoutDetails:
      type: object
      description: Detailed payout information for a reservation
      properties:
        reservation_id:
          type: string
          description: Accommodation reservation identifier
        property_id:
          type: string
          description: Property identifier
        payout_type:
          type: string
          description: 'Type of payout: GROSS, NET, or UNKNOWN.'
        payout_status:
          type: string
          description: 'Status of the payout: PENDING, PAID, PARTIALLY_PAID, CANCELLED, or UNKNOWN.'
        payment_tags:
          type: array
          description: Payment tags associated with the reservation.
          items:
            type: string
        total_price_of_reservation:
          type: object
          description: Breakdown of the total reservation price
          properties:
            total_amount_paid:
              $ref: '#/components/schemas/AmountPaid'
            total_amount_to_collect_at_property:
              $ref: '#/components/schemas/AmountToCollect'
        partner_payout:
          type: object
          description: Partner payout summary
          properties:
            total_payout:
              $ref: '#/components/schemas/AmountPayout'
            commissionable_price:
              $ref: '#/components/schemas/AmountCommissionable'
            commissions_and_charges:
              $ref: '#/components/schemas/AmountCommissionsAndCharges'
        payout:
          type: object
          description: Payout instruments
          properties:
            bank_transfers:
              type: array
              description: Bank transfer payouts
              items:
                type: object
                properties:
                  amount:
                    type: object
                    description: Contains information on the amount to be transferred.
                    properties:
                      value:
                        type: string
                        description: Payout amount.
                      currency:
                        type: string
                        description: Currency of the amount.
                      decimals:
                        type: integer
                        format: int32
                        description: Number of decimals in the amount.
                  status:
                    type: string
                    description: 'Status of the bank transfer payout: PENDING, PAID, or UNKNOWN.'
                  payout_date:
                    type: string
                    description: 'Date the amount is to be paid out to the partner. Format: YYYY-MM-DD.'
                  bank_transfer_reference:
                    type: string
                    description: Identifier of the bank transfer payout.
            virtual_credit_cards:
              type: array
              description: Virtual credit card payouts
              items:
                $ref: '#/components/schemas/PayoutVCC'
            customer_credit_cards:
              type: array
              description: Reserved for future Payments API updates.
              items:
                type: object
        price_breakdown:
          type: array
          description: Per-room price breakdown
          items:
            type: object
            properties:
              room_reservation_id:
                type: string
                description: Room reservation identifier
              charges:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      description: Charge type (e.g. Tax, COMMISSION)
                    amount:
                      $ref: '#/components/schemas/AmountCharges'
                    is_already_collected_from_guest:
                      type: string
                      description: If set to TRUE, the charged amount has already been collected from the guest and the partner does not need to collect anything. If set to FALSE, the partner has to collect the money at checkin. If set to UNKNOWN, no information is available.
                    is_included_total_partner_payout:
                      type: string
                      description: If set to TRUE, the charged amount is included in the payout and will be transferred to the partner. If set to FALSE, the charged amount is intended for another party, such as the government. If set to UNKNOWN, no information is available.
                    applicable_rate:
                      type:
                      - object
                      - 'null'
                      description: The rate applied to calculate the charge.
                      properties:
                        type:
                          type: string
                          description: How the rate is applied (e.g. PERCENTAGE).
                        value:
                          type: string
                          description: Rate value.
                        decimals:
                          type: integer
                          format: int32
                          description: Number of decimals in the rate value.
                    applicable_type:
                      type:
                      - array
                      - 'null'
                      description: The type of applicable rate.
                      items:
                        type: string
    BadRequestErrorResponse:
      type: object
      description: Response when the request doesn't have valid parameters
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
          description: The meta
        data:
          type: object
          description: Data containing required information
        errors:
          type: array
          description: List of errors for the response
          items:
            $ref: '#/components/schemas/Error'
        warnings:
          type: array
          description: List of warnings for the response
          items:
            $ref: '#/components/schemas/Warning'
    AmountVCCBalance:
      description: Contains information on the current balance of the VCC.
      properties:
        currency:
          type: string
          description: Currency of the amount.
        value:
          type: string
          description: Current balance of the VCC.
        decimals:
          type: integer
          format: int32
          description: Number of decimals in the amount.
    AmountCharges:
      description: Contains information on the total amount of all charges.
      properties:
        currency:
          type: string
          description: Currency of the amount.
        value:
          type: string
          description: Total amount of all charges.
        decimals:
          type: integer
          format: int32
          description: Number of decimals in the amount.
    InvalidTokenResponse:
      type: object
      description: Response when the authentication token is missing, invalid, or expired.
      properties:
        meta:
          $ref: '#/components/schemas/DefaultMeta'
        warnings:
          type: array
          description: List of warnings for the response
          maxItems: 0
          items: {}
        errors:
          type: array
          description: List of errors for the response
          items:
            type: object
            properties:
              message:
                type: string
                description: Error message
              code:
                type: string
                description: Error code
              details:
                type:
                - string
                - 'null'
                description: Additional error details
    VCCCardDetails:
      type: object
      description: Card details for a virtual credit card
      properties:
        cvc:
          type: string
          description: Card verification code
        card_name:
          type: string
          description: Name on the card
        card_number:
          type: string
          description: Card number
        card_type:
          type: string
          description: Type of the VCC
        card_expiry:
          type: string
          description: Card expiry date (MM/YY)
      required:
      - cvc
      - card_name
      - card_number
      - card_expiry
    PayoutVCC:
      type: object
      description: Virtual credit card included in the payout
      properties:
        activation_date:
          type: string
          format: date
          description: Date the VCC becomes active
        id:
          type: string
          description: VCC identifier
        current_balance:
          $ref: '#/components/schemas/AmountVCCBalance'
        expiration_date:
          type: string
          format: date
          description: Date the VCC expires
        status:
          type: string
          description: 'Possible VCC status values: NOT_LOADED, FUNDED, AVAILABLE, PARTIALLY_CHARGED, FULLY_CHARGED, CANCELLED, or UNKNOWN.'
        card_details:
          $ref: '#/components/schemas/VCCCardDetails'
      required:
      - id
      - status
      - current_balance
      - card_details
    PayoutDetailsResponse:
      type: object
      description: Response containing detailed payout information for a reservation
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
          description: Response metadata
        data:
          allOf:
          - $ref: '#/components/schemas/PayoutDetails'
          description: Payout details
        errors:
          type: array
          maxItems: 0
          items: {}
        warnings:
          type: array
          maxItems: 0
          items: {}
    ReservationDataNotFoundErrorResponse:
      type: object
      description: Response when the reservation data is not found
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
          description: The meta
        data:
          type: object
          description: Data containing required information
        errors:
          type: array
          description: List of errors for the response
          items:
            $ref: '#/components/schemas/Error'
        warnings:
          type: array
          description: List of warnings for the response
          items:
            $ref: '#/components/schemas/Warning'
    AmountPayout:
      description: Contains information on the total amount to be paid out to the partner.
      properties:
        currency:
          type: string
          description: Currency of the amount.
        value:
          type: string
          description: Total payout amount.
        decimals:
          type: integer
          format: int32
          description: Number of decimals in the amount.
    AmountToCollect:
      description: Contains information on the estimated amount the partner needs to collect from the guest at checkin.
      properties:
        currency:
          type: string
          description: Currency of the amount.
        value:
          type: string
          description: Estimated amount to be collected from the guest at checkin.
        decimals:
          type: integer
          format: int32
          description: Number of decimals in the amount.
    InternalServerErrorResponse:
      type: object
      description: Response when the request failed with an internal reason
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
          description: The meta
        data:
          type: object
          description: Data containing required information
        errors:
          type: array
          description: List of errors for the response
          items:
            $ref: '#/components/schemas/Error'
        warnings:
          type: array
          description: List of warnings for the response
          items:
            $ref: '#/components/schemas/Warning'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token for authentication. Use your API credentials to obtain a token.
x-tagGroups:
- name: API Endpoints
  tags:
  - Reservation payout details
  - Reservation breakdown
  - Bank transfer payout
  - VCC payout details, per accommodation reservation
  - VCCs to be charged
  - Refundable VCCs
  - Reservation Status API
- name: Documentation
  tags:
  - About Try it