Booking.com Payments by Booking configurations status 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 status
  description: Check the processing status of Payments by Booking configuration update requests.
paths:
  /connectivity-payments/pbb/configurations/status:
    post:
      tags:
      - Payments by Booking configurations status
      summary: Check Payments by Booking configuration request status
      description: Checks the processing status of Payments by Booking configuration update requests for given property IDs or a request ID.
      operationId: fetchAcceptedPBBConfigurationUpdateRequestsStatus
      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/PBBConfigurationUpdateStatusRequest'
            examples:
              statusByPropertyIds:
                summary: Status by property IDs
                value:
                  property_ids:
                  - 84729163
                  - 55318472
                  request_id: null
                  kyc_callback_url: https://partner.example.com/kyc/callback
              statusByRequestId:
                summary: Status by request ID
                value:
                  property_ids: []
                  request_id: req-a7c4e291-8f3b-4d6e-9c1a-2b5d8f0e3a7c
                  kyc_callback_url: https://partner.example.com/kyc/callback
              triggerForbidden:
                summary: 'Trigger 403 - Set Authorization header to: Bearer invalid-scope-token'
                value:
                  property_ids:
                  - 84729163
                  request_id: null
                  kyc_callback_url: https://www.example.com
              triggerServerError:
                summary: 'Trigger 500 - Set Authorization header to: Bearer trigger-500-test'
                value:
                  property_ids:
                  - 84729163
                  request_id: null
                  kyc_callback_url: https://www.example.com
        required: true
      responses:
        '200':
          description: Request accepted for processing
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PBBConfigurationUpdateStatusLookupResponse'
              examples:
                completedStatus:
                  summary: Completed status
                  value:
                    meta:
                      ruid: UQ-4a7c1f83-9e2b-5d6a-3f8c-1b4e9d0a7c2f
                    data:
                      config_update_details:
                      - property_id: '84729163'
                        request_id: req-a7c4e291-8f3b-4d6e-9c1a-2b5d8f0e3a7c
                        status: SUCCESSFUL
                        rejection_reason: null
                        requested_at: '2025-06-18T10:32:47Z'
                        actions: []
                      - property_id: '55318472'
                        request_id: req-a7c4e291-8f3b-4d6e-9c1a-2b5d8f0e3a7c
                        status: SUCCESSFUL
                        rejection_reason: null
                        requested_at: '2025-06-18T10:32:47Z'
                        actions: []
                    errors: []
                    warnings: []
                pendingKycAction:
                  summary: Pending with KYC action
                  value:
                    meta:
                      ruid: UQ-8b2e5c94-3f1a-7d4e-6b9c-2a5f8d1e4c7b
                    data:
                      config_update_details:
                      - property_id: '72615839'
                        request_id: req-c9f2b481-3e6d-7a5f-2c4b-8d1e9f0a3c5b
                        status: WAITING
                        rejection_reason: null
                        requested_at: '2025-06-18T14:07:52Z'
                        actions:
                        - reference: https://kyc.booking.com/submit?token=eyJhbGciOiJIUzI1NiJ9.partner.72615839
                          type: SUBMIT_KYC
                    errors: []
                    warnings: []
        '400':
          description: Invalid request payload.
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
              examples:
                missingRequiredFields:
                  summary: Missing required fields
                  value:
                    meta:
                      ruid: UQ-0d3f7a25-8b6c-4e9d-1f2a-7c5b9e3d8f1a
                    data: null
                    errors:
                    - description: Invalid request payload.
                      message: BAD_REQUEST
                      status_code: 400
                      debug_message: null
                    warnings: []
                propertiesNotCommonLegalEntity:
                  summary: Properties do not belong to common legal entity
                  value:
                    meta:
                      ruid: UQ-2a4c6e81-3f5b-7d9a-1c8e-4b0d2f6a8c3e
                    data: null
                    errors:
                    - description: The properties do not belong to a common legal entity.
                      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: []
        '404':
          description: The request id not found.
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PBBConfigUpdateRequestDataNotFoundErrorResponse'
              examples:
                requestNotFound:
                  summary: Request not found
                  value:
                    meta:
                      ruid: UQ-7f4a1c86-2e9d-5b3f-8a4c-1d6e0f9b7a3c
                    data: null
                    errors:
                    - description: The request id not found.
                      message: REQUEST_ID_NOT_FOUND
                      status_code: 404
                      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
    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'
    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
    Action:
      description: Pending actions to be performed by the partner
      properties:
        reference:
          type: string
          description: Reference to the action to be taken
        type:
          type: string
          description: 'Type of action to be taken. Possible values: SUBMIT_KYC.'
    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: {}
    PBBConfigurationUpdateStatusRequest:
      properties:
        property_ids:
          description: <=10 property IDs per request. All `property_ids` in a request should belong to a common legal entity ID. Required if `request_id` is not provided. Set to empty array if using `request_id`.
          type: array
          maxItems: 10
          items:
            type: integer
        request_id:
          description: Identifier of the accepted configuration request. Required if `property_ids` is not provided. Set to null if using `property_ids`.
          type:
          - string
          - 'null'
        kyc_callback_url:
          description: Callback URL where the user is redirected after completing pending actions (e.g. KYC submission).
          type: string
      required:
      - property_ids
      - request_id
      - kyc_callback_url
    PBBConfigurationUpdateStatusLookupDetails:
      description: Information regarding accepted Payments by Booking configuration update request status for properties
      properties:
        config_update_details:
          type: array
          description: Status information for accepted Payments by Booking configuration change requests for properties
          items:
            $ref: '#/components/schemas/PBBConfigurationUpdateStatusLookupDetail'
    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
    PBBConfigUpdateRequestDataNotFoundErrorResponse:
      description: Response when the requested resource doesn't exist
      properties:
        meta:
          $ref: '#/components/schemas/DefaultMeta'
        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'
    PBBConfigurationUpdateStatusLookupResponse:
      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/PBBConfigurationUpdateStatusLookupDetails'
        errors:
          type: array
          maxItems: 0
          items: {}
        warnings:
          type: array
          maxItems: 0
          items: {}
    PBBConfigurationUpdateStatusLookupDetail:
      description: Status information regarding accepted Payments by Booking configuration change request for a property
      properties:
        property_id:
          type: string
          description: Property identifier
        request_id:
          type: string
          description: Idempotency key of the latest accepted Payments by Booking configuration change request
        status:
          type: string
          description: Payments by Booking configuration change status for property
        rejection_reason:
          type: string
          description: Reason for rejection of Payments by Booking configuration change request
        requested_at:
          type: string
          description: Payments by Booking configuration change requested at
        actions:
          type: array
          description: Pending actions to be performed by the partner
          items:
            $ref: '#/components/schemas/Action'
    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