Weavr Trusted Payees API

openapi: 3.2.0
info:
  title: Weavr Trusted Payees API
  contact:
    name: Weavr
    url: https://weavr.io
  x-logo:
    url: https://storage.googleapis.com/weavr-cdn/weavr_logo-new.png
    backgroundColor: '#FFFFFF'
    altText: Weavr
  version: '1.0'
  description: 'Operations tagged Trusted Payees across 2 of this provider''s published API definitions: weavr-multi-openapi-original.yml, weavr-webhooks-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: Weavr Sandbox Environment
  url: https://sandbox.weavr.io/multi
- url: '""'
tags:
- name: Trusted Payees
  description: 'Manage a list of trusted payees for Outgoing wire transfers and Sends.


    Aside from convenience and a reduced chance of making errors when making transactions,

    this allows for the introduction an SCA exemption, where the account holder can request

    that transactions to `TRUSTED` payees to be exempted from the requirement to pass

    an SCA challenge every time.

    '
paths:
  /beneficiaries:
    post:
      tags:
      - Trusted Payees
      description: Payees (previously "beneficiaries"). Create one or more payees for the logged-in corporate or consumer identity.
      summary: Add payees
      operationId: beneficiaryBatchCreate
      x-permissions:
      - i:beneficiaries:create
      parameters:
      - $ref: '#/components/parameters/idempotency-ref'
      requestBody:
        $ref: '#/components/requestBodies/BeneficiaryBatchCreateRequest'
      responses:
        '200':
          $ref: '#/components/responses/BeneficiaryBatchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/Error'
      security:
      - auth_token: []
        api-key: []
    get:
      tags:
      - Trusted Payees
      description: Payees (previously "beneficiaries"). Retrieves the payees that match the query parameters.
      summary: Get all payees
      operationId: beneficiariesGet
      x-permissions:
      - i:beneficiaries:list
      parameters:
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      - name: batchId
        in: query
        required: false
        description: Search by the payee batch id.
        schema:
          type: array
          uniqueItems: true
          items:
            type: string
            pattern: ^[0-9]+$
      - name: group
        in: query
        required: false
        description: Search by the payee group.
        schema:
          type: array
          uniqueItems: true
          items:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/BeneficiaryPageResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/Error'
      security:
      - auth_token: []
        api-key: []
    servers:
    - description: Weavr Sandbox Environment
      url: https://sandbox.weavr.io/multi
  /beneficiaries/remove:
    post:
      tags:
      - Trusted Payees
      description: Payees (previously "beneficiaries"). Removes one or more payees from the payees list identified by the id path parameter used in the array.
      summary: Remove payees
      operationId: beneficiaryBatchRemove
      x-permissions:
      - i:beneficiaries:remove
      parameters:
      - $ref: '#/components/parameters/idempotency-ref'
      requestBody:
        $ref: '#/components/requestBodies/BeneficiaryBatchRemoveRequest'
      responses:
        '200':
          $ref: '#/components/responses/BeneficiaryBatchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/Error'
      security:
      - auth_token: []
        api-key: []
    servers:
    - description: Weavr Sandbox Environment
      url: https://sandbox.weavr.io/multi
  /beneficiaries/{id}:
    get:
      tags:
      - Trusted Payees
      description: Payees (previously "beneficiaries"). Retrieves a payee identified by the id path parameter.
      summary: Get a payee
      operationId: beneficiaryGet
      x-permissions:
      - i:beneficiaries:get
      parameters:
      - name: id
        in: path
        description: The unique identifier of a payee.
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      responses:
        '200':
          $ref: '#/components/responses/BeneficiaryResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/Error'
      security:
      - auth_token: []
        api-key: []
    servers:
    - description: Weavr Sandbox Environment
      url: https://sandbox.weavr.io/multi
  /beneficiaries/batch:
    get:
      tags:
      - Trusted Payees
      description: Payees (previously "beneficiaries"). Retrieves all payee batches matching the query parameters and that belong to the logged-in identity.
      summary: Get all payee batches
      operationId: beneficiaryBatchesGet
      x-permissions:
      - i:beneficiaries:list_batches
      parameters:
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      - name: state
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/BeneficiaryBatchState'
      - name: operation
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/BeneficiaryBatchOperation'
      - name: tag
        in: query
        required: false
        description: Filter by the payee batch tag. The exact tag must be provided, as wildcards are not supported. Leave out to fetch all entries.
        schema:
          type: array
          uniqueItems: true
          items:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/BeneficiaryBatchPageResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/Error'
      security:
      - auth_token: []
        api-key: []
    servers:
    - description: Weavr Sandbox Environment
      url: https://sandbox.weavr.io/multi
  /beneficiaries/batch/{id}:
    get:
      tags:
      - Trusted Payees
      description: Payees (previously "beneficiaries"). Retrieves the details of a payee batch identified by the batchId path parameter.
      summary: Get a batch of payees
      operationId: beneficiaryBatchGet
      x-permissions:
      - i:beneficiaries:get_batch
      parameters:
      - name: id
        in: path
        description: The unique identifier of a payee batch.
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      responses:
        '200':
          $ref: '#/components/responses/BeneficiaryBatchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/Error'
      security:
      - auth_token: []
        api-key: []
    servers:
    - description: Weavr Sandbox Environment
      url: https://sandbox.weavr.io/multi
  /beneficiaries/batch/{id}/challenges/otp/{channel}:
    post:
      tags:
      - Trusted Payees
      description: 'Payees (previously "beneficiaries"). Starts the verification process for updating the payees batch in which a one-time password is sent to a device belonging to the logged-in user that was previously enrolled through the `/authentication_factors/otp/{channel}` endpoint.


        You should only start this process if the payee update `state` is `PENDING_CHALLENGE`.


        _Note that on the Sandbox Environment, text messages are not sent and the one-time-password is always \"123456\"._

        '
      summary: Issue OTP to verify batch
      operationId: beneficiaryBatchSCAChallenge
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the Payee Batch Operation.
        schema:
          type: string
          pattern: ^[0-9]+$
      - $ref: '#/components/parameters/channel'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '409':
          $ref: '#/components/responses/BeneficiaryBatchSCAChallengeConflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/Error'
      security:
      - auth_token: []
        api-key: []
    servers:
    - description: Weavr Sandbox Environment
      url: https://sandbox.weavr.io/multi
  /beneficiaries/batch/{id}/challenges/otp/{channel}/verify:
    post:
      tags:
      - Trusted Payees
      description: 'Payees (previously "beneficiaries"). Completes the verification process for updating the payee batch.


        If the outcome of the verification is successful, the payee update batch is executed.


        _Note that on the Sandbox Environment, text messages are not sent and the verificationCode is always \"123456\"._

        '
      summary: Verify batch using OTP
      operationId: beneficiaryBatchSCAVerify
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the Payee Batch Operation.
        schema:
          type: string
          pattern: ^[0-9]+$
      - $ref: '#/components/parameters/channel'
      requestBody:
        $ref: '#/components/requestBodies/SCAVerifyRequest'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/BeneficiaryBatchSCAVerifyConflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/Error'
      security:
      - auth_token: []
        api-key: []
    servers:
    - description: Weavr Sandbox Environment
      url: https://sandbox.weavr.io/multi
  /beneficiaries/batch/{id}/challenges/push/{channel}:
    post:
      tags:
      - Trusted Payees
      description: 'Payees (previously "beneficiaries"). Starts the verification process for updating a payee batch in which a push notification is sent to a device belonging to the logged-in user that was previously enrolled through the `/authentication_factors/push/{channel}` endpoint.


        You should only start this process if the payee update operation `state` is `PENDING_CHALLENGE`.

        '
      summary: Issue push to verify batch
      operationId: beneficiaryBatchSCAChallengePush
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the Payee Batch Operation.
        schema:
          type: string
          pattern: ^[0-9]+$
      - $ref: '#/components/parameters/scaPushChannel'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '409':
          $ref: '#/components/responses/BeneficiaryBatchSCAChallengePushConflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/Error'
      security:
      - auth_token: []
        api-key: []
    servers:
    - description: Weavr Sandbox Environment
      url: https://sandbox.weavr.io/multi
webhooks:
  /beneficiaries/batch/watch:
    post:
      tags:
      - Trusted Payees
      summary: Beneficiary batch
      description: Notification that a Beneficiary batch has been submitted.
      operationId: beneficiary_batch_watch
      parameters:
      - $ref: '#/components/parameters/call-ref'
      - $ref: '#/components/parameters/published-timestamp'
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/signature-v2'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeneficiaryBatchEvent'
        required: true
      responses:
        '204':
          description: Success - No Content
    servers:
    - url: '""'
components:
  schemas:
    BankAccountDetailsBeneficiary:
      required:
      - bankAccountDetails
      type: object
      description: Represent the beneficiary bank account typically used in Outgoing Wire Transfer transactions.
      properties:
        address:
          maxLength: 150
          minLength: 1
          type: string
          description: The beneficiary's address.
        bankName:
          type: string
          description: The beneficiary's bank name.
        bankAddress:
          maxLength: 150
          minLength: 1
          type: string
          description: The beneficiary's bank address.
        bankCountry:
          type: string
          description: The beneficiary's bank country in ISO 3166 alpha-2 format.
          maxLength: 2
          minLength: 2
          pattern: ^[A-Z]{2}$
        bankAccountDetails:
          description: Details of the beneficiary bank account, depending on the type of transfer chosen.
          oneOf:
          - $ref: '#/components/schemas/IBANDetails'
          - $ref: '#/components/schemas/FasterPaymentsBankDetailsOrBACSBankDetails'
    BusinessBeneficiaryType:
      required:
      - businessName
      type: object
      properties:
        businessName:
          type: string
          description: 'The business beneficiary name. The allowed length and pattern is dependent on the beneficiary details type:


            `InstrumentDetailsBeneficiary` or `BankAccountDetailsBeneficiary` with `IBANDetails`: >= `1` character and <= `150` characters


            `BankAccountDetailsBeneficiary` with `FasterPaymentsBankDetailsOrBACSBankDetails`: >= `1` character and <= `140` characters with a pattern of `^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&*<>;\{@\r\n]*$`

            (please note that the `’` symbol is the unicode value U+2019 (right single quotation mark) and not the unicode value U+0027 (apostrophe))

            '
    FasterPaymentsBankDetailsOrBACSBankDetails:
      required:
      - accountNumber
      - sortCode
      type: object
      description: Bank details used in case the wire transfer is executed over Faster Payments.
      properties:
        accountNumber:
          type: string
          pattern: ^[0-9]{8}$
          description: Account number, required for wire transfer over Faster Payments.
        sortCode:
          type: string
          pattern: ^[0-9]{6}$
          description: Sort code, required for wire transfer over Faster Payments.
        secondaryReference:
          type: string
    BeneficiaryOperationBatchId:
      required:
      - batchId
      - operation
      type: object
      properties:
        batchId:
          description: The unique identifier of a Beneficiary.
          type: string
          pattern: ^[0-9]+$
        operation:
          description: Describes the operation that has occurred on a beneficiary batch.
          $ref: '#/components/schemas/BeneficiaryBatchOperation'
    Id:
      type: string
      pattern: ^[0-9]+$
    BeneficiaryValidationFailure:
      type: string
      enum:
      - INSTRUMENT_DETAILS_NOT_FOUND
      - BENEFICIARY_DETAILS_ALREADY_EXIST
      - BENEFICIARY_BELONGS_TO_SAME_IDENTITY
    InstrumentDetailsBeneficiary:
      required:
      - instrument
      type: object
      description: Represents a Weavr beneficiary instrument typically used in Send transactions.
      properties:
        instrument:
          $ref: '#/components/schemas/InstrumentId'
    SCAPushChannel:
      type: string
      enum:
      - AUTHY
      - BIOMETRIC
      description: '- "AUTHY": The push notification is sent on the user''s device using [Twilio Authy](https://www.twilio.com/authy)

        - "BIOMETRIC": The push notification is sent to the user''s device

        '
    IBANDetails:
      required:
      - iban
      type: object
      description: Bank details used in case the wire transfer is executed over SEPA or RIX
      properties:
        iban:
          type: string
          minLength: 15
          maxLength: 34
          pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$
          description: International Bank Account Number, required for wire transfer over SEPA or RIX
        bankIdentifierCode:
          type: string
          minLength: 8
          maxLength: 11
          pattern: ^[a-zA-Z0-9]{4}[a-zA-Z]{2}[a-zA-Z0-9]{2}[a-zA-Z0-9]{0,3}$
          description: BIC, for wire transfer over SEPA or RIX
    BasicBeneficiary:
      required:
      - trustLevel
      - beneficiaryInformation
      - beneficiaryDetails
      type: object
      properties:
        trustLevel:
          description: The value that determines whether a Beneficiary is trusted or not.
          $ref: '#/components/schemas/BeneficiaryTrustLevel'
        externalRefs:
          description: The id of the entity as it is represented on the caller system.
          type: array
          items:
            type: string
        group:
          description: A custom field that can be used to categorise a beneficiary for easier searching and filtering.
          type: string
          maxLength: 150
        beneficiaryInformation:
          description: The object representing the beneficiary details.
          oneOf:
          - $ref: '#/components/schemas/BusinessBeneficiaryType'
          - $ref: '#/components/schemas/ConsumerBeneficiaryType'
        beneficiaryDetails:
          description: The object representing the beneficiary instrument details.
          oneOf:
          - $ref: '#/components/schemas/InstrumentDetailsBeneficiary'
          - $ref: '#/components/schemas/BankAccountDetailsBeneficiary'
    Beneficiary:
      allOf:
      - $ref: '#/components/schemas/BasicBeneficiary'
      - type: object
        required:
        - id
        - relatedOperationBatches
        - state
        properties:
          id:
            type: string
            pattern: ^[0-9]+$
            description: The unique identifier of a Beneficiary.
          relatedOperationBatches:
            description: The object representing the list of batch IDs and the operations that occurred for each batch.
            type: array
            items:
              $ref: '#/components/schemas/BeneficiaryOperationBatchId'
          state:
            $ref: '#/components/schemas/BeneficiaryState'
          validationFailure:
            $ref: '#/components/schemas/BeneficiaryValidationFailure'
    SyntaxError:
      type: object
      description: Is returned as part of an HTTP error response whenever a syntax error is detected. A list of the fields together with their syntax error will be provided.
      properties:
        invalidFields:
          type: array
          items:
            type: object
            properties:
              params:
                type: array
                items:
                  type: string
              fieldName:
                type: string
              error:
                type: string
                enum:
                - REQUIRED
                - HAS_TEXT
                - REQUIRES
                - SIZE
                - RANGE
                - IN
                - NOT_IN
                - REGEX
                - EXACTLY
                - AT_LEAST
                - AT_MOST
                - ALL_OR_NONE
    BeneficiaryBatchOperation:
      type: string
      enum:
      - CREATE
      - REMOVE
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    Tag:
      type: string
      description: The tag field is a custom field that can be used to search and filter.
      maxLength: 50
      pattern: ^[a-zA-Z0-9_-]+$
    InstrumentType:
      type: string
      enum:
      - managed_cards
      - managed_accounts
    Nonce:
      type: string
      description: A randomly generated one-time use code.
      pattern: ^[0-9]{6}$
    BeneficiaryBatchState:
      type: string
      enum:
      - INITIALISED
      - FAILED
      - PENDING_CHALLENGE
      - CHALLENGE_FAILED
      - CHALLENGE_COMPLETED
      - COMPLETED
    SCAOtpChannel:
      type: string
      enum:
      - SMS
      description: '- "SMS": The one-time-password is sent as a text message

        '
    BeneficiaryBatch:
      type: object
      required:
      - operationBatchId
      - state
      properties:
        operationBatchId:
          $ref: '#/components/schemas/BeneficiaryOperationBatchId'
        tag:
          $ref: '#/components/schemas/Tag'
        state:
          $ref: '#/components/schemas/BeneficiaryBatchState'
    BeneficiaryTrustLevel:
      type: string
      description: The value that determines whether a Beneficiary is trusted or not.
      enum:
      - TRUSTED
    InstrumentId:
      required:
      - id
      - type
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        type:
          $ref: '#/components/schemas/InstrumentType'
    ConsumerBeneficiaryType:
      required:
      - fullName
      type: object
      properties:
        nationality:
          type: string
          description: The nationality of the consumer. Must be a valid ISO 3166-1 alpha-2 country code (e.g., 'GB', 'FR').
          pattern: ^[A-Z]{2}$
        dateOfBirth:
          type: string
          description: The date of birth of the consumer. Must be a valid date in ISO 8601 format (YYYY-MM-DD) and should not be a future date.
          format: date
        fullName:
          type: string
          description: 'The person beneficiary name. The allowed length and pattern is dependent on the beneficiary details type:


            `InstrumentDetailsBeneficiary` or `BankAccountDetailsBeneficiary` with `IBANDetails`: >= `1` character and <= `150` characters


            `BankAccountDetailsBeneficiary` with `FasterPaymentsBankDetailsOrBACSBankDetails`: >= `1` character and <= `140` characters with a pattern of `^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&*<>;\{@\r\n]*$`

            (please note that the `’` symbol is the unicode value U+2019 (right single quotation mark) and not the unicode value U+0027 (apostrophe))

            '
    BeneficiaryState:
      type: string
      enum:
      - INITIALISED
      - INVALID
      - PENDING_CHALLENGE
      - CHALLENGE_FAILED
      - ACTIVE
      - REMOVED
    BeneficiaryValidationFailure_2:
      type: string
      enum:
      - INSTRUMENT_DETAILS_NOT_FOUND
      - BENEFICIARY_DETAILS_ALREADY_EXIST
      - BENEFICIARY_BELONGS_TO_SAME_IDENTITY
      - BENEFICIARY_VALIDATION_FAILURE_UNKNOWN
    BeneficiaryBatchEventType:
      type: string
      enum:
      - INITIALISED
      - FAILED
      - PENDING_CHALLENGE
      - CHALLENGE_FAILED
      - CHALLENGE_COMPLETED
    BeneficiaryBatchEvent:
      required:
      - id
      - operation
      - eventType
      - publishedTimestamp
      - beneficiaries
      type: object
      properties:
        id:
          type: string
          pattern: ^[0-9]+$
        operation:
          $ref: '#/components/schemas/BeneficiaryBatchOperation'
        tag:
          maxLength: 50
          pattern: ^[a-zA-Z0-9_-]+$
          type: string
        publishedTimestamp:
          type: string
          pattern: ^[0-9]+$
          description: Epoch timestamp using millisecond precision.
        eventType:
          $ref: '#/components/schemas/BeneficiaryBatchEventType'
        beneficiaries:
          type: array
          items:
            $ref: '#/components/schemas/LegacyBeneficiary'
    LegacyBankAccountDetailsBeneficiary:
      type: object
      properties:
        beneficiaryName:
          maxLength: 100
          minLength: 1
          type: string
          description: The name of the beneficiary
        address:
          maxLength: 150
          type: string
          description: The beneficiary address
        bankName:
          maxLength: 150
          type: string
          description: The name of the beneficiary bank
        bankAddress:
          maxLength: 150
          type: string
          description: The beneficiary bank address
        bankCountry:
          maxLength: 2
          minLength: 2
          pattern: ^[A-Z]+$
          type: string
          description: The beneficiary bank country - using ISO 3166 alpha-2
        sepaBankDetails:
          $ref: '#/components/schemas/IBANDetails'
        fasterPaymentsBankDetails:
          $ref: '#/components/schemas/FasterPaymentsBankDetailsOrBACSBankDetails'
    LegacyBeneficiary:
      required:
      - trustLevel
      - id
      - beneficiaryInformation
      - beneficiaryDetails
      - state
      type: object
      properties:
        id:
          type: string
          pattern: ^[0-9]+$
        externalRefs:
          type: array
          items:
            type: string
        group:
          maxLength: 50
          pattern: ^[a-zA-Z0-9_-]+$
          type: string
        trustLevel:
          $ref: '#/components/schemas/BeneficiaryTrustLevel'
        beneficiaryInformation:
          type: object
          properties:
            businessBeneficiaryType:
              $ref: '#/components/schemas/BusinessBeneficiaryType'
            consumerBeneficiaryType:
              $ref: '#/components/schemas/ConsumerBeneficiaryType'
        beneficiaryDetails:
          type: object
          properties:
            instrumentDetailsBeneficiary:
              $ref: '#/components/schemas/InstrumentDetailsBeneficiary'
            bankAccountDetailsBeneficiary:
              $ref: '#/components/schemas/LegacyBankAccountDetailsBeneficiary'
        state:
          $ref: '#/components/schemas/BeneficiaryState'
        validationFailure:
          $ref: '#/components/schemas/BeneficiaryValidationFailure_2'
  responses:
    InternalServerError:
      description: Internal Server Error - There is a problem with the server. Please try again later.
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
    TooManyRequests:
      description: Too many requests.
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
        x-ratelimit-limit:
          $ref: '#/components/headers/x-ratelimit-limit'
        x-ratelimit-reset:
          $ref: '#/components/headers/x-ratelimit-reset'
    Unauthorized:
      description: Unauthorized - Your credentials or access token are invalid.
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
    BeneficiaryPageResponse:
      description: Success
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
      content:
        application/json:
          schema:
            type: object
            properties:
              beneficiaries:
                type: array
                items:
                  $ref: '#/components/schemas/Beneficiary'
              count:
                type: integer
                description: The total number of records (excluding the paging limit).
                format: int32
              responseCount:
                type: integer
                description: The total number of records returned in this response (always capped at 100).
                format: int32
    Forbidden:
      description: Forbidden - Access to the requested resource or action is forbidden.
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
      content:
        application/json:
          schema:
            type: object
            properties:
              errorCode:
                type: string
                enum:
                - INSUFFICIENT_PERMISSIONS
    BeneficiaryBatchSCAChallengePushConflict:
      description: Conflict
      content:
        application/json:
          schema:
            type: object
            properties:
              errorCode:
                type: string
                enum:
                - STATE_INVALID
                - CHANNEL_NOT_SUPPORTED
                - CHANNEL_NOT_REGISTERED
                - CHALLENGE_LIMIT_EXCEEDED
    BeneficiaryBatchSCAVerifyConflict:
      description: Conflict
      content:
        application/json:
          schema:
            type: object
            properties:
              errorCode:
                type: string
                enum:
                - STATE_INVALID
                - CHANNEL_NOT_SUPPORTED
                - CHANNEL_NOT_REGISTERED
                - VERIFICATION_CODE_EXPIRED
                - VERIFICATION_CODE_INVALID
                - ONE_CHALLENGE_LIMIT_REMAINING
                - CHALLENGE_LIMIT_EXCEEDED
    BeneficiaryBatchResponse:
      description: Success
      headers:
        request-ref:
          $ref: '#/components/headers/request-ref'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BeneficiaryBatch'
    BeneficiaryBatchPageResponse:


# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/weavr/refs/heads/main/openapi/weavr-trusted-payees-api-openapi.yml