openapi: 3.2.0
info:
  title: Payments by Booking Onboarding Payments eligibility details…
  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 eligibility details for partners
  description: Retrieve payments eligibility details for partners.
paths:
  /connectivity-payments/pbb/eligibility:
    post:
      tags:
      - Payments eligibility details for partners
      summary: Check payments eligibility
      description: Performs a bulk eligibility evaluation for a list of properties (property_ids) by returning their current payout configurations along with all available payout options, including eligibility metadata and any associated costs or restrictions.
      operationId: checkPaymentsEligibility
      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/PaymentsEligibilityRequest'
            examples:
              multipleProperties:
                summary: Eligibility check for multiple properties
                value:
                  property_ids:
                  - 84729163
                  - 55318472
                  - 63947281
              singleProperty:
                summary: Eligibility check for single property
                value:
                  property_ids:
                  - 38274916
              tooManyProperties:
                summary: Too many properties
                value:
                  property_ids:
                  - 84729163
                  - 55318472
                  - 63947281
                  - 72615839
                  - 91483620
                  - 47382916
                  - 29164738
                  - 61827394
                  - 83741629
                  - 54829163
                  - 70193846
              duplicateProperties:
                summary: Duplicate properties
                value:
                  property_ids:
                  - 84729163
                  - 55318472
                  - 84729163
                  - 72615839
              triggerForbidden:
                summary: 'Trigger 403 - Set Authorization header to: Bearer invalid-scope-token'
                value:
                  property_ids:
                  - 84729163
              triggerServerError:
                summary: 'Trigger 500 - Set Authorization header to: Bearer trigger-500-test'
                value:
                  property_ids:
                  - 84729163
        required: true
      responses:
        '200':
          description: Request for eligibility accepted.
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsEligibilityResponse'
              examples:
                mixedEligibility:
                  summary: Multiple properties with mixed eligibility
                  value:
                    meta:
                      ruid: UQ-a8f3c291-4b7e-9d2f-e6a1-3c8b5d0f7e2a
                    data:
                      payout_configurations:
                      - property_id: '84729163'
                        legal_entity_id: '7293851'
                        current_payout_configuration:
                          payin_collection_strategy: PARTIAL
                          payout_method: VCC
                          payout_frequency: DAILY
                          payout_netting: GROSS
                        payout_configuration_options:
                        - is_eligible: true
                          payin_collection_strategy: PARTIAL
                          payout_method: VCC
                          payout_frequency: []
                          payout_netting:
                          - GROSS
                          additional_requirements: []
                        - is_eligible: true
                          payin_collection_strategy: ALL
                          payout_method: BT
                          payout_frequency:
                          - DAILY
                          - WEEKLY
                          - MONTHLY
                          payout_netting:
                          - GROSS
                          - NET
                          additional_requirements: []
                        - is_eligible: false
                          payin_collection_strategy: ALL
                          payout_method: STRIPE
                          payout_frequency: []
                          payout_netting:
                          - GROSS
                          additional_requirements: []
                        vcc_activation_policy_code: '1'
                        bt_payout_cost_information:
                          value: '140'
                          type: PERCENTAGE
                          decimals: 2
                        is_config_update_supported_by_api: true
                      - property_id: '55318472'
                        legal_entity_id: '1847293'
                        current_payout_configuration:
                          payin_collection_strategy: ALL
                          payout_method: BT
                          payout_frequency: MONTHLY
                          payout_netting: NET
                        payout_configuration_options:
                        - is_eligible: true
                          payin_collection_strategy: PARTIAL
                          payout_method: VCC
                          payout_frequency: []
                          payout_netting:
                          - GROSS
                          additional_requirements: []
                        - is_eligible: true
                          payin_collection_strategy: ALL
                          payout_method: BT
                          payout_frequency:
                          - DAILY
                          - WEEKLY
                          - MONTHLY
                          payout_netting:
                          - GROSS
                          - NET
                          additional_requirements: []
                        - is_eligible: false
                          payin_collection_strategy: ALL
                          payout_method: STRIPE
                          payout_frequency: []
                          payout_netting:
                          - GROSS
                          additional_requirements: []
                        vcc_activation_policy_code: '2'
                        bt_payout_cost_information:
                          value: '150'
                          type: PERCENTAGE
                          decimals: 2
                        is_config_update_supported_by_api: true
                      - property_id: '63947281'
                        legal_entity_id: '9374621'
                        current_payout_configuration:
                          payin_collection_strategy: PARTIAL
                          payout_method: VCC
                          payout_frequency: null
                          payout_netting: GROSS
                        payout_configuration_options:
                        - is_eligible: true
                          payin_collection_strategy: PARTIAL
                          payout_method: VCC
                          payout_frequency: []
                          payout_netting:
                          - GROSS
                          additional_requirements: []
                        - is_eligible: false
                          payin_collection_strategy: ALL
                          payout_method: BT
                          payout_frequency:
                          - DAILY
                          - WEEKLY
                          - MONTHLY
                          payout_netting:
                          - GROSS
                          - NET
                          additional_requirements: []
                        - is_eligible: false
                          payin_collection_strategy: ALL
                          payout_method: STRIPE
                          payout_frequency: []
                          payout_netting:
                          - GROSS
                          additional_requirements: []
                        vcc_activation_policy_code: '1'
                        bt_payout_cost_information: null
                        is_config_update_supported_by_api: false
                    errors: []
                    warnings: []
                singlePropertyVcc:
                  summary: Single property VCC eligible
                  value:
                    meta:
                      ruid: UQ-c5d2e847-9a1f-4b73-8e6d-1f4c9a2b7e3d
                    data:
                      payout_configurations:
                      - property_id: '38274916'
                        legal_entity_id: '4829163'
                        current_payout_configuration:
                          payin_collection_strategy: PARTIAL
                          payout_method: VCC
                          payout_frequency: null
                          payout_netting: GROSS
                        payout_configuration_options:
                        - is_eligible: true
                          payin_collection_strategy: PARTIAL
                          payout_method: VCC
                          payout_frequency: []
                          payout_netting:
                          - GROSS
                          additional_requirements: []
                        - is_eligible: false
                          payin_collection_strategy: ALL
                          payout_method: BT
                          payout_frequency:
                          - DAILY
                          - WEEKLY
                          - MONTHLY
                          payout_netting:
                          - GROSS
                          - NET
                          additional_requirements: []
                        - is_eligible: false
                          payin_collection_strategy: ALL
                          payout_method: STRIPE
                          payout_frequency: []
                          payout_netting:
                          - GROSS
                          additional_requirements: []
                        vcc_activation_policy_code: '3'
                        bt_payout_cost_information: null
                        is_config_update_supported_by_api: true
                    errors: []
                    warnings: []
                stripeEligibleProperties:
                  summary: STRIPE eligible properties
                  value:
                    meta:
                      ruid: UQ-f9b1d473-2e8a-5c6f-a3b9-7d0e4f2c8a1b
                    data:
                      payout_configurations:
                      - property_id: '72615839'
                        legal_entity_id: '6139'
                        current_payout_configuration:
                          payin_collection_strategy: ALL
                          payout_method: STRIPE
                          payout_frequency: null
                          payout_netting: GROSS
                        payout_configuration_options:
                        - is_eligible: true
                          payin_collection_strategy: PARTIAL
                          payout_method: VCC
                          payout_frequency: []
                          payout_netting:
                          - GROSS
                          additional_requirements: []
                        - is_eligible: true
                          payin_collection_strategy: ALL
                          payout_method: BT
                          payout_frequency:
                          - DAILY
                          - WEEKLY
                          - MONTHLY
                          payout_netting:
                          - GROSS
                          - NET
                          additional_requirements: []
                        - is_eligible: true
                          payin_collection_strategy: ALL
                          payout_method: STRIPE
                          payout_frequency: []
                          payout_netting:
                          - GROSS
                          additional_requirements:
                          - name: REQUIRES_KYC_FOR_PAYOUT
                            action: COMPLETE_KYC_AFTER_ONBOARDING
                        vcc_activation_policy_code: '4'
                        bt_payout_cost_information:
                          value: '200'
                          type: PERCENTAGE
                          decimals: 2
                        is_config_update_supported_by_api: true
                      - property_id: '91483620'
                        legal_entity_id: '6182739'
                        current_payout_configuration:
                          payin_collection_strategy: ALL
                          payout_method: STRIPE
                          payout_frequency: null
                          payout_netting: GROSS
                        payout_configuration_options:
                        - is_eligible: true
                          payin_collection_strategy: PARTIAL
                          payout_method: VCC
                          payout_frequency: []
                          payout_netting:
                          - GROSS
                          additional_requirements: []
                        - is_eligible: true
                          payin_collection_strategy: ALL
                          payout_method: BT
                          payout_frequency:
                          - DAILY
                          - WEEKLY
                          - MONTHLY
                          payout_netting:
                          - GROSS
                          - NET
                          additional_requirements: []
                        - is_eligible: true
                          payin_collection_strategy: ALL
                          payout_method: STRIPE
                          payout_frequency: []
                          payout_netting:
                          - GROSS
                          additional_requirements: []
                        vcc_activation_policy_code: '4'
                        bt_payout_cost_information:
                          value: '200'
                          type: PERCENTAGE
                          decimals: 2
                        is_config_update_supported_by_api: true
                    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-b3e7a182-6c4d-9f1e-2a8b-5d0c7e3f9a4b
                    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-e4c8b291-7d5a-2f3e-1b9c-6a0d8f4e2c7b
                    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
    PaymentsEligibilityModel:
      description: Data containing required information
      properties:
        payout_configurations:
          type: array
          description: Details about payout configurations for property_ids
          items:
            $ref: '#/components/schemas/PaymentsEligibility'
    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'
    PaymentsEligibilityRequest:
      properties:
        property_ids:
          description: <=10 property IDs per request.
          type: array
          maxItems: 10
          items:
            type: integer
      required:
      - property_ids
    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
    CurrentPayoutOption:
      description: Current payout configuration for a property
      properties:
        payin_collection_strategy:
          type: string
          description: 'Payin collection strategy. Possible values: PARTIAL, ALL.'
        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_frequency:
          type:
          - string
          - 'null'
          description: 'How often payouts are executed to the partner for this property, as per the current configuration. Applies mainly when payout_method is ''BT''. Possible values: DAILY, WEEKLY, MONTHLY. For VCC, null is returned.'
        payout_netting:
          type: string
          description: 'Defines how commissions or payment-related costs are deducted directly from each payout. Possible values: GROSS, NET.'
    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: {}
    PaymentsEligibilityResponse:
      description: Response containing payments eligibility information for the specified property IDs
      properties:
        meta:
          $ref: '#/components/schemas/DefaultMeta'
        data:
          $ref: '#/components/schemas/PaymentsEligibilityModel'
        errors:
          type: array
          maxItems: 0
          items: {}
        warnings:
          type: array
          maxItems: 0
          items: {}
    PayoutOption:
      description: A payout option for the property
      properties:
        is_eligible:
          type: boolean
          description: Indicates if this payout option is currently eligible
        payin_collection_strategy:
          type: string
          description: 'Payin collection strategy. Possible values: PARTIAL, ALL.'
        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_frequency:
          type: array
          description: Available payout frequencies for this option. Applies mainly when payout_method is 'BT'
          items:
            type: string
            description: 'Available payout frequency. Possible values: DAILY, WEEKLY, MONTHLY.'
        payout_netting:
          type: array
          description: Defines how commissions or payment-related costs are deducted directly from each payout
          items:
            type: string
            description: 'Defines how commissions or payment-related costs are deducted directly from each payout. Possible values: GROSS, NET.'
        additional_requirements:
          type: array
          description: List of additional requirements for this payout option
          items:
            $ref: '#/components/schemas/AdditionalRequirement'
    PaymentsEligibility:
      description: Payout configuration for a property
      properties:
        property_id:
          type: string
          description: Property identifier
        legal_entity_id:
          type: string
          description: Legal entity identifier
        current_payout_configuration:
          $ref: '#/components/schemas/CurrentPayoutOption'
        payout_configuration_options:
          type: array
          description: List of other payout configuration options
          items:
            $ref: '#/components/schemas/PayoutOption'
        vcc_activation_policy_code:
          type: string
          description: VCC activation policy code
        bt_payout_cost_information:
          $ref: '#/components/schemas/BTPayoutCostInformation'
        is_config_update_supported_by_api:
          type: boolean
          description: Indicates whether the property can be onboarded to Payments by Booking via the Payments Configuration API.
    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
    BTPayoutCostInformation:
      description: Bank transfer payout cost information
      properties:
        value:
          type: string
        type:
          type: string
        decimals:
          type: integer
          format: int32
    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'
    AdditionalRequirement:
      description: Additional requirement to be met for a property to be eligible for Payments by Booking
      properties:
        name:
          type: string
          description: Name of the requirement
        action:
          type: string
          description: Action needed to complete the requirement
  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