Yapily Constraints API

openapi: 3.0.1
info:
  title: Yapily Beneficiaries Application Beneficiaries Constraints API
  description: Application and User Beneficiaries endpoints for managing reusable payment counterparties.
  version: 12.4.0
  contact:
    name: Yapily Support
    url: https://docs.yapily.com/resources/support
    email: support@yapily.com
servers:
- url: https://api.yapily.com
security:
- basicAuth: []
tags:
- description: The constraints endpoints can be used to retrieve institution specific data requirements and rules that will apply when performing other operations.
  name: Constraints
paths:
  /institutions/constraints/payments:
    get:
      description: Retrieve institution specific constraints for payment authorisation and submission requests
      operationId: getPaymentConstraintsRulesByInstitution
      x-beta: true
      parameters:
      - description: Unique Id(s) of the `Institution`(s) to retrieve the Payment Constraints for. Multiple institutionIds need to be separated by `,`
        name: institutionIds
        required: true
        in: query
        schema:
          type: array
          items:
            type: string
      - description: Country code of the `Institution`(s). Ensure that the country code matches the respective institutionIds; any mismatch will result in an HTTP 404 error response.
        in: query
        name: institutionCountryCode
        required: true
        schema:
          type: string
      - description: Type of payment to retrieve payment constraints for
        in: query
        name: paymentType
        required: true
        schema:
          type: string
          enum:
          - DOMESTIC_PAYMENT
          - DOMESTIC_INSTANT_PAYMENT
          - DOMESTIC_VARIABLE_RECURRING_PAYMENT
          - DOMESTIC_SCHEDULED_PAYMENT
          - DOMESTIC_PERIODIC_PAYMENT
          - INTERNATIONAL_PAYMENT
          - INTERNATIONAL_SCHEDULED_PAYMENT
          - INTERNATIONAL_PERIODIC_PAYMENT
      - description: The path on the API that is associated with the operation for which constraints are to be retrieved
        in: query
        name: endpointPath
        required: false
        schema:
          type: string
      - description: The HTTP method that is associated with the operation for which constraints are to be retrieved
        in: query
        name: endpointMethod
        required: false
        schema:
          type: string
          enum:
          - POST
          - PATCH
          - PUT
          - GET
          - DELETE
      responses:
        '200':
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiListResponseOfPaymentConstraints'
          description: Ok
        '400':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/400-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Bad Request.
        '401':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/401-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Either authentication credentials were not supplied, or they were invalid.
        '404':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/404-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Not Found.
        '500':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/500-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Unexpected Error
      summary: Get Payment Constraints Rules
      tags:
      - Constraints
      x-mint:
        content: '<Info>Learn more: [Payment Constraints](/payments/payment-resources/payment-constraints) for institution-specific requirements</Info>'
  /institutions/constraints/data:
    get:
      description: Get Data Constraints Rules against an Institution for Account Authorisation requests
      operationId: getAccountConstraintsRulesByInstitution
      x-beta: true
      parameters:
      - description: Unique Id(s) of the `Institution`(s) to retrieve the Data Constraints for. Multiple institutionIds need to be separated by `,`
        name: institutionIds
        required: true
        in: query
        schema:
          type: array
          items:
            type: string
      - description: Country code of the `Institution`(s). Ensure that the country code matches the respective institutionIds; any mismatch will result in an HTTP 404 error response.
        in: query
        name: institutionCountryCode
        required: true
        schema:
          type: string
      - description: The path on the API that is associated with the operation for which constraints are to be retrieved
        in: query
        name: endpointPath
        required: false
        schema:
          type: string
      - description: The HTTP method that is associated with the operation for which constraints are to be retrieved
        in: query
        name: endpointMethod
        required: false
        schema:
          type: string
          enum:
          - POST
          - PATCH
          - PUT
          - GET
          - DELETE
      responses:
        '200':
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiListResponseOfDataConstraints'
          description: Ok
        '400':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/400-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Bad Request.
        '401':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/401-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Either authentication credentials were not supplied, or they were invalid.
        '404':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/404-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Not Found.
        '500':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/500-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Unexpected Error
      summary: Get Data Constraints Rules
      tags:
      - Constraints
components:
  schemas:
    PaymentConstraintsResponse:
      required:
      - institutionId
      - institutionCountry
      - paymentType
      - request
      type: object
      properties:
        institutionId:
          type: string
          description: The id to represent the `Institution`.
          example: modelo-sandbox
        institutionCountryCode:
          type: string
          description: 2 letter ISO Country code of the `Institution`.
          example: GB
        endpointPath:
          type: string
          description: Define the applicable API end point.
        endpointMethod:
          type: string
          description: Https Method for the endpoint.
        paymentType:
          $ref: '#/components/schemas/PaymentTypeOfConstraints'
        request:
          $ref: '#/components/schemas/RequestConstraints'
    ResponseMeta:
      type: object
      properties:
        tracingId:
          type: string
    ApiError:
      type: object
      description: Provides details of the error that has occurred.
      properties:
        code:
          type: integer
          description: __Mandatory__. Numeric `HTTP` status code associated with the error.
          format: int32
        institutionError:
          $ref: '#/components/schemas/InstitutionError'
        message:
          type: string
          description: __Mandatory__. Description of the exact error that has been experienced.
        source:
          type: string
        status:
          type: string
          description: __Mandatory__. Textual description of the `HTTP` error status type.
        tracingId:
          type: string
          description: __Optional__.  A unique identifier assigned by Yapily for the request that can be used for support purposes.
    RawResponse:
      deprecated: true
      type: object
      description: '[DEPRECATED] Interaction (raw request and response) that occurred with the `Institution` in order to fulfil a request.'
      properties:
        request:
          $ref: '#/components/schemas/RawRequest'
        duration:
          type: string
          format: iso8601
        headers:
          type: object
          additionalProperties:
            type: string
        resultCode:
          type: integer
          format: int32
        result:
          type: object
    ApiListResponseOfDataConstraints:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/DataConstraintsResponse'
      example:
        meta:
          tracingId: a43049c1dbc04d6f8c8e2dfdc523217a
        data:
        - institutionId: mock-sandbox
          institutionCountryCode: GB
          endpointPath: /account-auth-requests
          endpointMethod: POST
          request:
            headers:
              title: Header
              type: object
              properties:
                psuID:
                  title: PSU Id
                  type: string
                  description: __Mandatory__. The psu id
            body:
              required:
              - institutionId
              type: object
              properties:
                userUuid:
                  title: User UUID
                  type: string
                  format: uuid
                institutionId:
                  title: Institution Identifier
                  type: string
                  description: __Mandatory__. The reference to the `Institution` which identifies which institution the authorisation request is sent to.
                  example: yapily-mock
                oneTimeToken:
                  title: One Time Token
                  type: boolean
                  description: "__Conditional__. Used to receive a `oneTimeToken` rather than a `consentToken` at the `callback` for additional security. This can only be used when the `callback` is set. \n\nSee [Using a callback with an OTT (Optional)](/open-banking-flow/handling-redirects/callback-url) for more information."
                  example: false
                callback:
                  title: Callback
                  type: string
                  description: "__Optional__. The server to redirect the user to after the user complete the authorisation at the `Institution`. \n\nSee [Using a callback (Optional)](/open-banking-flow/handling-redirects/callback-url) for more information."
                  example: https://display-parameters.com
                accountRequest:
                  title: Account Request
                  type: object
                  properties:
                    transactionFrom:
                      title: Transaction From Date
                      type: string
                      description: __Optional__. Used to specify the lower bound on when to pull transaction. This should be declared when accessing transaction older than 90 days for banks in the [CBI Globe](/data/financial-data-resources/data-restrictions#cbi-globe-gateway).
                      format: date-time
                    transactionTo:
                      title: Transaction To Date
                      type: string
                      description: __Optional__. When performing a request using the consent, this is the latest date of transaction records that can be retrieved.
                      format: date-time
                    expiresAt:
                      title: Expires At
                      type: string
                      description: '__Optional__. Used to set a hard date for when the user''s associated `Consent` will expire.


                        **Note**: If this supported by the bank, specifying this is property is opting out of having a long-lived consent that can be perpetually re-authorised by the user. This will add an `expiresAt` field on the `Consent` object which will render it unusable after this date.


                        **Note**: This is not supported by every `Institution`. In such case, the request will not fail but the property will be ignored and the created `Consent` will not have an expiry date.'
                      format: date-time
                    accountIdentifiers:
                      title: Account Info
                      required:
                      - accountIdentification
                      type: object
                      properties:
                        accountId:
                          type: string
                          description: __Conditional__. Unique identifier of the account.
                          example: '500000000000000000000001'
                        accountIdentification:
                          title: Account Identifications
                          required:
                          - identification
                          - type
                          type: object
                          properties:
                            type:
                              enum:
                              - SORT_CODE
                              - ACCOUNT_NUMBER
                              - IBAN
                              - BBAN
                              - BIC
                              - PAN
                              - MASKED_PAN
                              - MSISDN
                              - BSB
                              - NCC
                              - ABA
                              - ABA_WIRE
                              - ABA_ACH
                              - EMAIL
                              - ROLL_NUMBER
                              - BLZ
                              - IFS
                              - CLABE
                              - CTN
                              - BRANCH_CODE
                              - VIRTUAL_ACCOUNT_ID
                              title: Account Identification Type
                              type: string
                              description: "__Mandatory__. Used to describe the format of the account.\n\n See [Account Identification Combinations](/payments/payment-resources/intro-to-payment-execution#account-identifications-combinations) for more information on when to specify each type."
                              example: SORT_CODE
                            identification:
                              title: Account Identification
                              type: string
                              description: "__Mandatory__. The value associated with the account identification type.\n\n See [Account Identification Combinations](/payments/payment-resources/intro-to-payment-execution#account-identifications-combinations) for more information on the format of the values."
                              example: '401016'
                      description: "__Conditional__. Used to create a request for the balance of the account specified. Once the user authorises the request, only the balance can be obtained by executing [GET Account Balances](./#get-account-balances).\n\n This can be specified in conjunction with `accountIdentifiersForTransaction` to generate a `Consent` that can both access the accounts balance and transactions."
                    accountIdentifiersForTransaction:
                      type: array
                      items:
                        required:
                        - accountIdentification
                        type: object
                        properties:
                          accountId:
                            type: string
                            description: __Conditional__. Unique identifier of the account.
                            example: '500000000000000000000001'
                          accountIdentification:
                            title: Account Identifications
                            required:
                            - identification
                            - type
                            type: object
                            properties:
                              type:
                                enum:
                                - SORT_CODE
                                - ACCOUNT_NUMBER
                                - IBAN
                                - BBAN
                                - BIC
                                - PAN
                                - MASKED_PAN
                                - MSISDN
                                - BSB
                                - NCC
                                - ABA
                                - ABA_WIRE
                                - ABA_ACH
                                - EMAIL
                                - ROLL_NUMBER
                                - BLZ
                                - IFS
                                - CLABE
                                - CTN
                                - BRANCH_CODE
                                - VIRTUAL_ACCOUNT_ID
                                title: Account Identification Type
                                type: string
                                description: "__Mandatory__. Used to describe the format of the account.\n\n See [Account Identification Combinations](/payments/payment-resources/intro-to-payment-execution#account-identifications-combinations) for more information on when to specify each type."
                                example: SORT_CODE
                              identification:
                                title: Account Identification
                                type: string
                                description: "__Mandatory__. The value associated with the account identification type.\n\n See [Account Identification Combinations](/payments/payment-resources/intro-to-payment-execution#account-identifications-combinations) for more information on the format of the values."
                                example: '401016'
                      description: "__Conditional__. Used to create a request for the transactions of the account specified. Once the user authorises the request, only the transactions can be obtained by executing [GET Account Transactions](./#get-account-transactions). \n\nThis can be specified in conjunction with `accountIdentifiersForBalance` to generate a `Consent` that can both access the accounts balance and transactions."
                    accountIdentifiersForBalance:
                      type: array
                      items:
                        required:
                        - accountIdentification
                        type: object
                        properties:
                          accountId:
                            type: string
                            description: __Conditional__. Unique identifier of the account.
                            example: '500000000000000000000001'
                          accountIdentification:
                            title: Account Identifications
                            required:
                            - identification
                            - type
                            type: object
                            properties:
                              type:
                                enum:
                                - SORT_CODE
                                - ACCOUNT_NUMBER
                                - IBAN
                                - BBAN
                                - BIC
                                - PAN
                                - MASKED_PAN
                                - MSISDN
                                - BSB
                                - NCC
                                - ABA
                                - ABA_WIRE
                                - ABA_ACH
                                - EMAIL
                                - ROLL_NUMBER
                                - BLZ
                                - IFS
                                - CLABE
                                - CTN
                                - BRANCH_CODE
                                - VIRTUAL_ACCOUNT_ID
                                title: Account Identification Type
                                type: string
                                description: "__Mandatory__. Used to describe the format of the account.\n\n See [Account Identification Combinations](/payments/payment-resources/intro-to-payment-execution#account-identifications-combinations) for more information on when to specify each type."
                                example: SORT_CODE
                              identification:
                                title: Account Identification
                                type: string
                                description: "__Mandatory__. The value associated with the account identification type.\n\n See [Account Identification Combinations](/payments/payment-resources/intro-to-payment-execution#account-identifications-combinations) for more information on the format of the values."
                                example: '401016'
                      description: "__Conditional__. Used to create a request for the transactions of the account specified. Once the user authorises the request, only the transactions can be obtained by executing [GET Account Transactions](./#get-account-transactions). \n\nThis can be specified in conjunction with `accountIdentifiersForBalance` to generate a `Consent` that can both access the accounts balance and transactions."
                    featureScope:
                      title: Feature Scope
                      type: array
                      items:
                        type: string
                      description: Used to describe what functions are supported by the associated `Institution`
                  description: Account authorisation request schema
              description: The request body containing an `AccountAuthorisationRequest` json payload
    SchemaType:
      type: string
      enum:
      - array
      - boolean
      - integer
      - number
      - object
      - string
    InstitutionError:
      type: object
      description: Raw error details provided by the `Institution`, when it was the error source.
      properties:
        errorMessage:
          type: string
          description: Textual description of the `Institution` error.
        httpStatusCode:
          type: integer
          description: Numeric HTTP status code associated with the `Institution` error.
          format: int32
    ApiResponseError:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ApiError'
        raw:
          deprecated: true
          type: array
          items:
            $ref: '#/components/schemas/RawResponse'
      description: 'Used to return errors from the bank from each request


        - `400` - Returned by any `POST` endpoint when the body does not conform to the contract

        - `401` - Returned by any endpoint when an invalid `authToken` is used for authentication

        - `403` - Returned by any [Financial Data](/api-reference#financial-data) and any [Payments](/api-reference#payments) endpoint when the `Consent` is no longer authorised to access financial data or to make a payment

        - `404` - Returned by any endpoint where there are path parameters and the path parameters supplied are unable to find the desired resource

        - `409` - Returned by any `POST` endpoint when creating a resource that conflicts with any other existing resource e.g. [Create User](/api-reference/addUser)

        - `424` - Returned by any [Financial Data](/api-reference#financial-data) and any [Payments](/api-reference#payments) endpoint when the feature to be accessed is not supported by the `Institution`.

        - `500` - Returned by any endpoint when Yapily is down. If you encounter any false positives, please [notify us](mailto:support@yapily.com)'
      example:
        error:
          tracingId: 74b13ce8ed51419f92c5d609e04532de
          code: 424
          institutionError:
            errorMessage: '{"Code":"500 Internal Server Error","Id":"5ff8d331-4282-41e0-b5ef-1ac9ac39f009","Message":"Technical Error. Please try again later","Errors":[{"ErrorCode":"UK.OBIE.UnexpectedError","Message":"There was a problem processing your request. Please try again later"}]}'
            httpStatusCode: 500
          source: INSTITUTION
          status: FAILED_DEPENDENCY
    Schema:
      type: object
      properties:
        title:
          type: string
        maximum:
          type: number
        exclusiveMaximum:
          type: number
        minimum:
          type: number
        exclusiveMinimum:
          type: number
        pattern:
          type: string
          format: regex
        maxItems:
          type: integer
          minimum: 0
        minItems:
          type: integer
          minimum: 0
        uniqueItems:
          type: boolean
        required:
          type: array
          items:
            type: string
          minItems: 1
          uniqueItems: true
        enum:
          type: array
          items: {}
          minItems: 1
          uniqueItems: false
        type:
          $ref: '#/components/schemas/SchemaType'
        contains:
          $ref: '#/components/schemas/Schema'
        not:
          $ref: '#/components/schemas/Schema'
        if:
          $ref: '#/components/schemas/Schema'
        then:
          $ref: '#/components/schemas/Schema'
        else:
          $ref: '#/components/schemas/Schema'
        allOf:
          type: array
          items:
            $ref: '#/components/schemas/Schema'
        oneOf:
          type: array
          items:
            $ref: '#/components/schemas/Schema'
        anyOf:
          type: array
          items:
            $ref: '#/components/schemas/Schema'
        items:
          $ref: '#/components/schemas/Schema'
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Schema'
        description:
          type: string
        format:
          type: string
        default: {}
        example: {}
        dependentRequired:
          description: dependentRequired keyword is used to satisfy dependency between fields
          type: object
          additionalProperties:
            type: array
            items:
              type: string
            uniqueItems: true
            default: []
        $defs:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Schema'
        $ref:
          type: string
        x-yapily-annotations:
          type: object
          properties:
            lastUpdatedAt:
              type: string
              format: date-time
        x-yapily-validations:
          type: object
          properties:
            maxDurationFromNow:
              type: string
              format: duration
      additionalProperties: false
    PaymentTypeOfConstraints:
      title: Payment Type
      type: string
      description: Payment type associated with constraints.
      enum:
      - DOMESTIC_PAYMENT
      - DOMESTIC_INSTANT_PAYMENT
      - DOMESTIC_VARIABLE_RECURRING_PAYMENT
      - DOMESTIC_SCHEDULED_PAYMENT
      - DOMESTIC_PERIODIC_PAYMENT
      - INTERNATIONAL_PAYMENT
      - INTERNATIONAL_SCHEDULED_PAYMENT
      - INTERNATIONAL_PERIODIC_PAYMENT
    DataConstraintsResponse:
      required:
      - institutionId
      - institutionCountry
      - request
      type: object
      properties:
        institutionId:
          type: string
          description: The id to represent the `Institution`.
          example: modelo-sandbox
        institutionCountryCode:
          type: string
          description: 2 letter ISO Country code of the `Institution`.
          example: GB
        endpointPath:
          type: string
          description: Define the applicable API end point.
        endpointMethod:
          type: string
          description: Https Method for the endpoint.
        request:
          $ref: '#/components/schemas/RequestConstraints'
    Pagination:
      type: object
      properties:
        totalCount:
          type: integer
          format: int64
        self:
          $ref: '#/components/schemas/FilterAndSort'
        next:
          $ref: '#/components/schemas/Next'
    ApiListResponseOfPaymentConstraints:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseListMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/PaymentConstraintsResponse'
      example:
        meta:
          tracingId: 661471ddb4344113a2d185b861cb3dcf
        data:
        - institutionId: mock-sandbox
          institutionCountryCode: GB
          endpointPath: /payments
          endpointMethod: POST
          paymentType: DOMESTIC_PAYMENT
          request:
            headers:
              title: Header
              type: object
              properties:
                psuID:
                  title: PSU Id
                  type: string
                  description: ''
            body:
              title: Payment Request
              required:
              - payee
              - amount
              - paymentIdempotencyId
              - type
              type: object
              properties:
                paymentIdempotencyId:
                  title: Payment Idempotency Id
                  pattern: ^.{1,35}$
                  type: string
                  description: Id for the payment
                type:
                  enum:
                  - DOMESTIC_PAYMENT
                  title: Payment Type
                  type: string
                  description: type of the payment
                contextType:
                  default: OTHER
                  enum:
                  - BILL
                  - GOODS
                  - SERVICES
                  - OTHER
                  - PERSON_TO_PERSON
                  title: Context Type
                  type: string
                  description: __Optional__. The payment context code. This defaults to `OTHER` if not specified.
                reference:
                  title: Reference
                  pattern: ^.{1,18}$
                  type: string
                  description: __Mandatory__. The payment reference or description. Limited to a maximum of 18 characters long.
                  example: Bill payment
                payee:
                  title: Payee
                  required:
                  - accountIdentifications
                  - name
                  type: object
                  properties:
                    name:
                      title: Name
                      pattern: ^.{1,18}$
                      type: string
                      description: __Mandatory__. The account holder name of the beneficiary.
                      example: Jane Doe
                    accountIdentifications:
                      title: Account Identifications
                      type: array
                      items:
                        required:
                        - identification
                        - type
                     

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/yapily/refs/heads/main/openapi/yapily-constraints-api-openapi.yml