UK Open Banking Funds Confirmations API

openapi: 3.2.0
info:
  title: Confirmation of Funds API Specification Funds Confirmations…
  description: 'Swagger for Confirmation of Funds API Specification.


    **Please Note**: There are no optional fields, if a field is not marked as “Required” it is a Conditional field.'
  termsOfService: https://www.openbanking.org.uk/terms
  contact:
    name: Service Desk
    email: ServiceDesk@openbanking.org.uk
  license:
    name: open-licence
    url: https://www.openbanking.org.uk/open-licence
  version: 4.0.1
servers:
- url: /open-banking/v4.0/cbpii
tags:
- name: Funds Confirmations
paths:
  /funds-confirmations:
    post:
      tags:
      - Funds Confirmations
      summary: Create a Funds Confirmation Request
      description: Enables a CBPII to check whether a PSU has sufficient available funds for a CBPII transaction.
      operationId: CreateFundsConfirmations
      parameters:
      - $ref: '#/components/parameters/x-fapi-auth-date'
      - $ref: '#/components/parameters/x-fapi-customer-ip-address'
      - $ref: '#/components/parameters/x-fapi-interaction-id'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/x-customer-user-agent'
      - $ref: '#/components/parameters/x-client-id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OBFundsConfirmation1'
        description: Default
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201FundsConfirmationsCreated'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '405':
          $ref: '#/components/responses/405Error'
        '406':
          $ref: '#/components/responses/406Error'
        '415':
          $ref: '#/components/responses/415Error'
        '429':
          $ref: '#/components/responses/429Error'
        '500':
          $ref: '#/components/responses/500Error'
      security:
      - PSUOAuth2Security:
        - fundsconfirmations
components:
  headers:
    RateLimit:
      required: false
      description: 'TPPs __must__ refer to ASPSP developer portals for further information on any rate limit policies, if the headers are supported and any additional requirements.


        A server uses the "RateLimit" response header field to communicate the current service limit for a quota policy for a particular partition key.


        Example:

        `RateLimit: "default";r=50;t=30`


        The **REQUIRED** "r" parameter value conveys the remaining quota units for the identified policy.


        The **OPTIONAL** "t" parameter value conveys the time window reset time for the identified policy.

        '
      schema:
        type: string
    RateLimit-Policy:
      required: false
      description: 'TPPs __must__ refer to ASPSP developer portals for further information on any rate limit policies, if the headers are supported and any additional requirements.


        A non-empty list of Quota Policy Items. The Item value __MUST__ be a String.


        Example:

        `RateLimit-Policy: "default";q=100;w=10`


        The **REQUIRED** "q" parameter indicates the quota allocated by this policy measured in quota units.


        The **OPTIONAL** "w" parameter value conveys a time window.

        '
      schema:
        type: string
  responses:
    429Error:
      description: Too Many Requests
      headers:
        Retry-After:
          description: Number in seconds to wait
          schema:
            type: integer
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
    201FundsConfirmationsCreated:
      description: Funds Confirmation Created
      headers:
        x-fapi-interaction-id:
          required: true
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBFundsConfirmationResponse1'
        application/json:
          schema:
            $ref: '#/components/schemas/OBFundsConfirmationResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBFundsConfirmationResponse1'
    500Error:
      description: Internal Server Error
      headers:
        x-fapi-interaction-id:
          required: true
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
        application/json:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
    415Error:
      description: Unsupported Media Type
      headers:
        x-fapi-interaction-id:
          required: true
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
    406Error:
      description: Not Acceptable
      headers:
        x-fapi-interaction-id:
          required: true
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
    405Error:
      description: Method Not Allowed
      headers:
        x-fapi-interaction-id:
          required: true
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
    401Error:
      description: Unauthorized
      headers:
        x-fapi-interaction-id:
          required: true
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
    400Error:
      description: Bad request
      headers:
        x-fapi-interaction-id:
          required: true
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
        application/json:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
    403Error:
      description: Forbidden
      headers:
        x-fapi-interaction-id:
          required: true
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
        application/json:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
  schemas:
    OBError1:
      type: object
      properties:
        ErrorCode:
          $ref: '#/components/schemas/OBExternalStatusReason1Code'
        Message:
          description: 'A description of the error that occurred. e.g., ''A mandatory field isn''t supplied'' or ''RequestedExecutionDateTime must be in future''

            OBL doesn''t standardise this field'
          type: string
          minLength: 1
          maxLength: 500
        Path:
          description: Recommended but optional reference to the JSON Path of the field with error, e.g., Data.Initiation.InstructedAmount.Currency
          type: string
          minLength: 1
          maxLength: 500
        Url:
          description: URL to help remediate the problem, or provide more information, or to API Reference, or help etc
          type: string
      required:
      - ErrorCode
      additionalProperties: false
      minProperties: 1
    OBFundsConfirmation1:
      type: object
      required:
      - Data
      properties:
        Data:
          type: object
          required:
          - ConsentId
          - Reference
          - InstructedAmount
          properties:
            ConsentId:
              description: Unique identification as assigned by the ASPSP to uniquely identify the funds confirmation consent resource.
              type: string
              minLength: 1
              maxLength: 128
            Reference:
              description: Unique reference, as assigned by the CBPII, to unambiguously refer to the request related to the payment transaction.
              type: string
              minLength: 1
              maxLength: 35
            InstructedAmount:
              type: object
              required:
              - Amount
              - Currency
              description: Amount of money to be confirmed as available funds in the debtor account. Contains an Amount and a Currency.
              properties:
                Amount:
                  description: A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.
                  type: string
                  pattern: ^\d{1,13}$|^\d{1,13}\.\d{1,5}$
                Currency:
                  description: A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".
                  type: string
                  pattern: ^[A-Z]{3,3}$
      additionalProperties: false
    OBFundsConfirmationResponse1:
      type: object
      required:
      - Data
      properties:
        Data:
          type: object
          required:
          - FundsConfirmationId
          - ConsentId
          - CreationDateTime
          - FundsAvailable
          - Reference
          - InstructedAmount
          properties:
            FundsConfirmationId:
              description: Unique identification as assigned by the ASPSP to uniquely identify the funds confirmation resource.
              type: string
              minLength: 1
              maxLength: 40
            ConsentId:
              description: Unique identification as assigned by the ASPSP to uniquely identify the funds confirmation consent resource.
              type: string
              minLength: 1
              maxLength: 128
            CreationDateTime:
              description: "Date and time at which the resource was created. All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone. An example is below:\n2017-04-05T10:43:07+00:00"
              type: string
              format: date-time
            FundsAvailable:
              description: Flag to indicate the result of a confirmation of funds check.
              type: boolean
            Reference:
              description: Unique reference, as assigned by the CBPII, to unambiguously refer to the request related to the payment transaction.
              type: string
              minLength: 1
              maxLength: 35
            InstructedAmount:
              type: object
              required:
              - Amount
              - Currency
              description: Amount of money to be confirmed as available funds in the debtor account. Contains an Amount and a Currency.
              properties:
                Amount:
                  description: A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.
                  type: string
                  pattern: ^\d{1,13}$|^\d{1,13}\.\d{1,5}$
                Currency:
                  description: A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".
                  type: string
                  pattern: ^[A-Z]{3,3}$
        Links:
          $ref: '#/components/schemas/Links'
        Meta:
          $ref: '#/components/schemas/Meta'
      additionalProperties: false
    Links:
      type: object
      description: Links relevant to the payload
      properties:
        Self:
          type: string
          format: uri
        First:
          type: string
          format: uri
        Prev:
          type: string
          format: uri
        Next:
          type: string
          format: uri
        Last:
          type: string
          format: uri
      additionalProperties: false
      required:
      - Self
    OBErrorResponse1:
      description: An array of detail error codes, and messages, and URLs to documentation to help remediation.
      type: object
      properties:
        Id:
          description: A unique reference for the error instance, for audit purposes, in case of unknown/unclassified errors.
          type: string
          minLength: 1
          maxLength: 40
        Code:
          description: Deprecated <br>High level textual error code, to help categorise the errors.
          type: string
          minLength: 1
          example: 400 BadRequest
          maxLength: 40
        Message:
          description: Deprecated <br>Brief Error message
          type: string
          minLength: 1
          example: There is something wrong with the request parameters provided
          maxLength: 500
        Errors:
          items:
            $ref: '#/components/schemas/OBError1'
          type: array
          minItems: 1
      required:
      - Errors
      additionalProperties: false
    OBExternalStatusReason1Code:
      description: Low level textual error code, for all enum values see `OBExternalStatusReason1Code` in *OB_Internal_CodeSet* [here](https://github.com/OpenBankingUK/External_Internal_CodeSets)
      type: string
      minLength: 4
      maxLength: 4
      example: U001
    Meta:
      title: MetaData
      type: object
      description: Meta Data relevant to the payload
      properties:
        TotalPages:
          type: integer
          format: int32
        FirstAvailableDateTime:
          $ref: '#/components/schemas/ISODateTime'
        LastAvailableDateTime:
          $ref: '#/components/schemas/ISODateTime'
      additionalProperties: false
    ISODateTime:
      description: "All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone. An example is below:\n2017-04-05T10:43:07+00:00"
      type: string
      format: date-time
  parameters:
    Authorization:
      in: header
      name: Authorization
      required: true
      description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750
      schema:
        type: string
    x-client-id:
      in: header
      name: x-client-id
      required: false
      description: "Only used if an ASPSP requires the client ID in order to return rate limit headers. \n\nTPPs __must__ refer to ASPSP developer portals for further information on any rate limit policies, if the headers are supported and any additional requirements.\n\nThis header __must not__ be used for client authentication\n"
      schema:
        type: string
    x-customer-user-agent:
      in: header
      name: x-customer-user-agent
      description: Indicates the user-agent that the PSU is using.
      required: false
      schema:
        type: string
    x-fapi-auth-date:
      in: header
      name: x-fapi-auth-date
      required: false
      description: "The time when the PSU last logged in with the TPP. \nAll dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: \nSun, 10 Sep 2017 19:43:31 UTC"
      schema:
        type: string
        pattern: ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} (GMT|UTC)$
    x-fapi-interaction-id:
      in: header
      name: x-fapi-interaction-id
      required: false
      description: An RFC4122 UID used as a correlation id.
      schema:
        type: string
    x-fapi-customer-ip-address:
      in: header
      name: x-fapi-customer-ip-address
      required: false
      description: The PSU's IP address if the PSU is currently logged in with the TPP.
      schema:
        type: string
  securitySchemes:
    TPPOAuth2Security:
      type: oauth2
      description: TPP client credential authorisation flow with the ASPSP
      flows:
        clientCredentials:
          tokenUrl: https://authserver.example/token
          scopes:
            fundsconfirmations: Funds confirmation entitlement
    PSUOAuth2Security:
      type: oauth2
      description: OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
      flows:
        authorizationCode:
          authorizationUrl: https://authserver.example/authorization
          tokenUrl: https://authserver.example/token
          scopes:
            fundsconfirmations: Funds confirmation entitlement
x-provenance:
  method: harvested
  publisher: UK Open Banking
  source: https://raw.githubusercontent.com/OpenBankingUK/read-write-api-specs/master/dist/openapi/confirmation-funds-openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)