Booking.com Payments by Booking configurations API

openapi: 3.2.0
info:
  title: Payments by Booking Onboarding Payments by Booking…
  description: Manage Payments by Booking onboarding configurations, check property eligibility for different payout options, and monitor the processing status of configuration update requests.
  contact:
    name: Connectivity Team
    url: https://connect.booking.com
    email: connectivity@booking.com
  version: '1.0'
servers:
- url: https://payments-by-booking-onboarding-api.wiremockapi.cloud/
  description: Mock (stateful simulator)
- url: https://payments-api.booking.com/
  description: Production
security:
- bearerAuth: []
tags:
- name: Payments by Booking configurations
  description: Update Payments by Booking payout configurations for properties.
paths:
  /connectivity-payments/pbb/configurations:
    post:
      tags:
      - Payments by Booking configurations
      summary: Update Payments by Booking configurations
      description: Updates Payments by Booking configurations and returns processing status
      operationId: updatePBBConfigurations
      parameters:
      - name: accept-version
        in: header
        required: false
        schema:
          type: string
          default: '1.0'
        example: '1.0'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PBBConfigurationUpdateRequest'
            examples:
              singleConfigMultipleProperties:
                summary: Single config with multiple properties
                value:
                  payout_configurations:
                  - legal_entity_id: '7293851'
                    property_ids:
                    - 84729163
                    - 55318472
                    payout_method: VCC
                    payout_netting: GROSS
                    payout_frequency: null
                    payin_collection_strategy: PARTIAL
              multipleConfigsDifferentOptions:
                summary: Multiple configs with different payout methods
                value:
                  payout_configurations:
                  - legal_entity_id: '7293851'
                    property_ids:
                    - 84729163
                    payout_method: VCC
                    payout_netting: GROSS
                    payout_frequency: null
                    payin_collection_strategy: PARTIAL
                  - legal_entity_id: '1847293'
                    property_ids:
                    - 55318472
                    payout_method: BT
                    payout_netting: NET
                    payout_frequency: MONTHLY
                    payin_collection_strategy: ALL
              stripeConfiguration:
                summary: STRIPE configuration
                value:
                  payout_configurations:
                  - legal_entity_id: '6182739'
                    property_ids:
                    - 72615839
                    - 91483620
                    payout_method: STRIPE
                    payout_netting: GROSS
                    payout_frequency: null
                    payin_collection_strategy: ALL
              btFrequencyChange:
                summary: BT frequency change
                value:
                  payout_configurations:
                  - legal_entity_id: '9374621'
                    property_ids:
                    - 63947281
                    payout_method: BT
                    payout_netting: GROSS
                    payout_frequency: WEEKLY
                    payin_collection_strategy: ALL
              tooManyProperties:
                summary: Too many properties
                value:
                  payout_configurations:
                  - legal_entity_id: '7293851'
                    property_ids:
                    - 84729163
                    - 55318472
                    - 63947281
                    - 72615839
                    - 91483620
                    - 47382916
                    - 29164738
                    - 61827394
                    - 83741629
                    - 54829163
                    - 70193846
                    payout_method: VCC
                    payout_netting: GROSS
                    payout_frequency: null
                    payin_collection_strategy: PARTIAL
              triggerForbidden:
                summary: 'Trigger 403 - Set Authorization header to: Bearer invalid-scope-token'
                value:
                  payout_configurations:
                  - legal_entity_id: '7293851'
                    property_ids:
                    - 84729163
                    payout_method: VCC
                    payout_netting: GROSS
                    payout_frequency: null
                    payin_collection_strategy: PARTIAL
              triggerServerError:
                summary: 'Trigger 500 - Set Authorization header to: Bearer trigger-500-test'
                value:
                  payout_configurations:
                  - legal_entity_id: '7293851'
                    property_ids:
                    - 84729163
                    payout_method: VCC
                    payout_netting: GROSS
                    payout_frequency: null
                    payin_collection_strategy: PARTIAL
        required: true
      responses:
        '202':
          description: Request accepted for processing
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PBBConfigurationUpdateStatusResponse'
              examples:
                mixedAcceptedRejected:
                  summary: Mixed accepted and rejected
                  value:
                    meta:
                      ruid: UQ-d1f5b392-8a4c-7e2b-3d9f-6c1a8b5e4d7f
                    data:
                      config_update_details:
                      - property_id: '84729163'
                        request_id: req-a7c4e291-8f3b-4d6e-9c1a-2b5d8f0e3a7c
                        status: ACCEPTED
                        rejection_reason: null
                        requested_at: '2025-06-18T10:32:47Z'
                      - property_id: '55318472'
                        request_id: null
                        status: REJECTED
                        rejection_reason: The property signed up with Payments By Booking in the past, or the requested payout configuration change is not supported.
                        requested_at: null
                    errors: []
                    warnings: []
                allAccepted:
                  summary: All accepted
                  value:
                    meta:
                      ruid: UQ-7e3a9b14-5c8d-2f6e-4a1b-9d7c0e5f3b2a
                    data:
                      config_update_details:
                      - property_id: '72615839'
                        request_id: req-b8d5f302-9a4c-5e7d-1b2f-4c6e9a1d8b3e
                        status: ACCEPTED
                        rejection_reason: null
                        requested_at: '2025-06-18T11:14:23Z'
                      - property_id: '91483620'
                        request_id: req-b8d5f302-9a4c-5e7d-1b2f-4c6e9a1d8b3e
                        status: ACCEPTED
                        rejection_reason: null
                        requested_at: '2025-06-18T11:14:23Z'
                    errors: []
                    warnings: []
                rejectedDifferentLegalEntities:
                  summary: Rejected - different legal entities
                  value:
                    meta:
                      ruid: UQ-2c6a4f81-7b3e-5d9c-8f2a-1e4b9d7c3f6a
                    data:
                      config_update_details:
                      - property_id: '84729163'
                        request_id: null
                        status: REJECTED
                        rejection_reason: The requested configuration has properties from different legal entities.
                        requested_at: null
                      - property_id: '55318472'
                        request_id: null
                        status: REJECTED
                        rejection_reason: The requested configuration has properties from different legal entities.
                        requested_at: null
                    errors: []
                    warnings: []
                rejectedSameAsCurrentConfig:
                  summary: Rejected - same as current config
                  value:
                    meta:
                      ruid: UQ-9f4b2e73-1d6c-8a5f-3e7b-4c1d9a2f6e8b
                    data:
                      config_update_details:
                      - property_id: '38274916'
                        request_id: null
                        status: REJECTED
                        rejection_reason: The requested configuration is the same as current.
                        requested_at: null
                    errors: []
                    warnings: []
                rejectedUnsupportedSwitch:
                  summary: Rejected - unsupported configuration switch
                  value:
                    meta:
                      ruid: UQ-6a1c8d35-4f7b-9e2a-5c3d-8b0f4e7a1c9d
                    data:
                      config_update_details:
                      - property_id: '63947281'
                        request_id: null
                        status: REJECTED
                        rejection_reason: The property signed up with Payments By Booking in the past, or the requested payout configuration change is not supported.
                        requested_at: null
                    errors: []
                    warnings: []
                stripeMixedResult:
                  summary: STRIPE - mixed result
                  value:
                    meta:
                      ruid: UQ-3b7e9f42-8c1a-6d4e-2f5b-9a0c3d7e1f4b
                    data:
                      config_update_details:
                      - property_id: '72615839'
                        request_id: req-c9f2b481-3e6d-7a5f-2c4b-8d1e9f0a3c5b
                        status: ACCEPTED
                        rejection_reason: null
                        requested_at: '2025-06-18T14:07:52Z'
                      - property_id: '47382916'
                        request_id: null
                        status: REJECTED
                        rejection_reason: The requested configuration is ineligible for the property.
                        requested_at: null
                    errors: []
                    warnings: []
        '400':
          description: Invalid request payload.
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
              examples:
                tooManyProperties:
                  summary: Too many properties
                  value:
                    meta:
                      ruid: UQ-5d8c3a71-2f9b-4e6d-1a7c-3b0f9e4d8c2a
                    data: null
                    errors:
                    - description: The number of property_ids exceeds the maximum allowed limit of 10.
                      message: BAD_REQUEST
                      status_code: 400
                      debug_message: null
                    warnings: []
                duplicateProperties:
                  summary: Duplicate properties
                  value:
                    meta:
                      ruid: UQ-1e9f4b82-6c3d-5a7f-8b2e-4d0c9a1f7b3e
                    data: null
                    errors:
                    - description: The request contains duplicate property_ids.
                      message: BAD_REQUEST
                      status_code: 400
                      debug_message: null
                    warnings: []
        '401':
          description: Unauthorized. Missing or invalid authentication token.
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidTokenResponse'
              examples:
                unauthorizedRequest:
                  summary: Invalid or expired token
                  value:
                    meta:
                      ruid: UQ-c7d2e481-9f3a-4b6c-8e5d-1a2b3c4d5e6f
                    data: null
                    errors:
                    - description: Invalid or expired token.
                      message: UNAUTHORIZED
                      status_code: 401
                      debug_message: null
                    warnings: []
        '403':
          description: Access Denied!
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedRequestResponse'
              examples:
                accessDenied:
                  summary: Insufficient permissions
                  value:
                    meta:
                      ruid: UQ-d8e3f592-0a4b-5c7d-9f6e-2b3c4d5e6f7a
                    data: null
                    errors:
                    - description: Access Denied!
                      message: FORBIDDEN
                      status_code: 403
                      debug_message: null
                    warnings: []
        '429':
          description: Rate limit exceeded. Maximum 30 requests per minute.
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersion'
        '500':
          description: The request failed with an internal server error.
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
              examples:
                internalError:
                  summary: Internal server error
                  value:
                    meta:
                      ruid: UQ-e9f4a6b3-1b5c-6d8e-0a7f-3c4d5e6f7a8b
                    data: null
                    errors:
                    - description: The request failed with an internal server error.
                      message: INTERNAL_SERVER_ERROR
                      status_code: 500
                      debug_message: null
                    warnings: []
components:
  schemas:
    Warning:
      type: object
      description: Warning information
      properties:
        message:
          type: string
          description: Warning message
          example: string
    PBBConfigurationUpdateStatusDetails:
      description: Information regarding Payments by Booking configuration change request for properties
      properties:
        config_update_details:
          type: array
          description: Status information for Payments by Booking configuration change requested for properties
          items:
            $ref: '#/components/schemas/PBBConfigurationUpdateStatusDetail'
    PBBConfigurationUpdateStatusDetail:
      description: Status information regarding validated Payments by Booking configuration change request for a property (update response)
      properties:
        property_id:
          type: string
          description: Property identifier
        request_id:
          type:
          - string
          - 'null'
          description: Idempotency key of the latest accepted Payments by Booking configuration change request. Null when status is REJECTED.
        status:
          type: string
          description: Payments by Booking configuration change status for property
        rejection_reason:
          type:
          - string
          - 'null'
          description: Reason for rejection of Payments by Booking configuration change request. Null when request is accepted.
        requested_at:
          type:
          - string
          - 'null'
          description: Payments by Booking configuration change requested at. Null when status is REJECTED.
    PBBConfigurationUpdateStatusResponse:
      description: Response of Payments by Booking configurations update request with property-level processing status of accepted configuration change request.
      properties:
        meta:
          $ref: '#/components/schemas/DefaultMeta'
        data:
          $ref: '#/components/schemas/PBBConfigurationUpdateStatusDetails'
        errors:
          type: array
          maxItems: 0
          items: {}
        warnings:
          type: array
          maxItems: 0
          items: {}
    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
        debug_message:
          type:
          - string
          - 'null'
          description: Detailed debug message for the error
    PBBConfigurationUpdateRequest:
      properties:
        payout_configurations:
          type: array
          items:
            $ref: '#/components/schemas/PayoutConfiguration'
    InvalidTokenResponse:
      type: object
      description: Response when the authentication token is missing, invalid, or expired.
      properties:
        meta:
          $ref: '#/components/schemas/DefaultMeta'
        data:
          type:
          - object
          - 'null'
          description: Response data (null for error responses)
        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
          maxItems: 0
          items: {}
    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
          - 'null'
          description: Response data (null for error responses)
        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'
    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
          - 'null'
          description: Response data (null for error responses)
        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'
    DefaultMeta:
      type: object
      description: Metadata for the response
      properties:
        ruid:
          type: string
          description: Request unique identifier
          example: string
    PayoutConfiguration:
      required:
      - legal_entity_id
      - property_ids
      - payout_method
      - payout_netting
      - payin_collection_strategy
      properties:
        legal_entity_id:
          type: string
        property_ids:
          description: <=10 property IDs per request. All `property_ids` in a request should belong to a common legal entity ID.
          type: array
          maxItems: 10
          items:
            type: integer
        payout_method:
          type: string
          description: 'The method by which Booking.com remits payments to the partner for this property. Possible values: VCC, BT, STRIPE.'
        payout_netting:
          type: string
          description: 'Defines how commissions or payment-related costs are deducted directly from each payout. Possible values: GROSS, NET.'
        payout_frequency:
          type:
          - string
          - 'null'
          description: 'How often payouts should be executed to the partner for this property. Applies mainly when payout_method is ''BT''. Possible values: DAILY, WEEKLY, MONTHLY. Set to null when payout_method is VCC or STRIPE.'
        payin_collection_strategy:
          type: string
          description: 'Payin collection strategy. Possible values: PARTIAL, ALL.'
    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'
  headers:
    ApiVersion:
      description: The response includes the API version used. Either the version requested, or the default if none was specified in the request.
      schema:
        type: string
      example: '1.0'
  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:
  - Payments eligibility details for partners
  - Payments by Booking configurations
  - Payments by Booking configurations status
- name: Documentation
  tags:
  - About Try it