ClearBank External Institution Payments V6 API

openapi: 3.2.0
info:
  title: ClearBank CHAPS RTGS FI API V6 External Institution Payments V6 API
  version: 6.0-CHAPS
tags:
- name: ExternalInstitutionPaymentsV6
paths:
  /payments/chaps/v6/institution-payments:
    post:
      tags:
      - ExternalInstitutionPaymentsV6
      description: Create an outbound bank-to-bank payment. This endpoint is used to send CHAPS Pacs.009 payments between financial institutions and is only available to authorised institutions.
      operationId: ExternalCreateInstitutionPayment-v6
      parameters:
      - $ref: '#/components/parameters/ParametersOpenapi_Authorization'
      - $ref: '#/components/parameters/ParametersOpenapi_DigitalSignature'
      - $ref: '#/components/parameters/ParametersOpenapi_RequestIdentifier'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInstitutionPaymentDtoV6'
            example:
              instructionIdentification: INSTR-INST-001
              endToEndIdentification: E2E-INST-001
              interBankSettlementAmount:
                amount: 100000
                currency: GBP
              sourceAccount:
                iban: GB29NWBK60161331926819
              debtor:
                name: Acme Bank Ltd
              creditorAccount:
                schemeName: SortcodeAccountNumber
                identification: 040004-12345678
              creditor:
                name: Example Financial Institution
              purpose: TREA
              categoryPurpose: TREA
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/CreateInstitutionPaymentDtoV6'
          text/json:
            schema:
              $ref: '#/components/schemas/CreateInstitutionPaymentDtoV6'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreateInstitutionPaymentDtoV6'
        required: true
      responses:
        '202':
          description: Accepted
          headers:
            X-Correlation-Id:
              $ref: '#/components/headers/HeadersOpenapi_CorrelationIdentifier'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PaymentCreatedResponseDtoV6'
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentCreatedResponseDtoV6'
            text/json:
              schema:
                $ref: '#/components/schemas/PaymentCreatedResponseDtoV6'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
components:
  schemas:
    ClearBankSchema_PaymentId:
      description: ClearBank identifier that uniquely identifies the payment instruction. Supplied in response to the original payment instruction request.
      type: string
      format: uuid
    ProblemDetails:
      description: Properties of a given error
      type: object
      required:
      - type
      - title
      properties:
        detail:
          description: A human-readable description of the problem unique to the instance of the problem.
          type: string
        errors: {}
        instance:
          description: A URI that uniquely identifies the problem being reported.
          type: string
        status:
          description: The HTTP response code returned by the API.
          type: string
        title:
          description: A short, human-readable summary of the problem type.
          type: string
        type:
          description: A URI that uniquely identifies the problem type being reported
          type: string
    PartyDetailsDtoV6:
      required:
      - name
      - postalAddress
      - lei
      type: object
      properties:
        name:
          description: Name of the financial institution.
          type: string
          minLength: 1
          maxLength: 140
          example: Acme Bank Ltd
          pattern: ^[0-9a-zA-Z/\-\?:\(\)\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$
        postalAddress:
          $ref: '#/components/schemas/PartyAddressDetailsDtoV6'
          type: object
          description: Information that locates and identifies a specific address, as defined by postal services. Required.
        lei:
          description: Legal Entity Identifier of the party. Required.
          type: string
          minLength: 20
          maxLength: 20
          pattern: ^[A-Z0-9]{18,18}[0-9]{2,2}$
          example: 5493001KJH8B2Q3L5X79
      additionalProperties: false
    UnstructuredRemittanceInformationDtoV6:
      type: object
      description: Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.
      properties:
        unstructured:
          description: Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form.
          type: string
          minLength: 1
          maxLength: 140
          pattern: ^[0-9a-zA-Z/\-\?:\(\)\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$
          example: Invoice payment INV-2026-001
      additionalProperties: false
    PurposeCodeV6:
      description: Underlying reason for the payment transaction, as published in an external purpose code list.
      type: string
      enum:
      - BKFE
      - BKIP
      - BKPP
      - CBLK
      - ACCT
      - CASH
      - COLL
      - CSDB
      - DEPT
      - INTC
      - INTP
      - LIMA
      - NETT
      - EXTD
      - OTCD
      - REPO
      - SBSC
      - SLEB
      - AGRT
      - AREN
      - BEXP
      - BOCE
      - COMC
      - CPYR
      - GDSV
      - GSCB
      - LICF
      - ROYA
      - SERV
      - SUBS
      - SUPP
      - TRAD
      - CHAR
      - COMT
      - ECPR
      - EPAY
      - CLPR
      - COMP
      - DBTC
      - HLRP
      - HLST
      - INPC
      - INPR
      - INSC
      - INSU
      - INTE
      - LBRI
      - LIFI
      - LOAN
      - LOAR
      - PENO
      - PPTI
      - RELG
      - TRFD
      - FORW
      - FXNT
      - BLDM
      - BNET
      - CDBL
      - CORT
      - CPKC
      - EDUC
      - FAND
      - FEES
      - GIFT
      - GOVT
      - INSM
      - IVPT
      - REBT
      - REFU
      - RENT
      - REOD
      - TCSC
      - CMDT
      - DERI
      - DIVD
      - FREX
      - HEDG
      - INVS
      - SAVG
      - SECU
      - TREA
      - FNET
      - FUTR
      - DNTS
      - HLTI
      - LTCF
      - MDCS
      - VIEW
      - SWFP
      - SWPP
      - SWRS
      - SWUF
      - ADCS
      - ALMY
      - BECH
      - BENE
      - BONU
      - COMM
      - HREC
      - PEFC
      - PENS
      - SALA
      - SSBE
      - LREB
      - LREV
      - ESTX
      - HSTX
      - INTX
      - PTXP
      - RDTX
      - TAXS
      - VATX
      - WHLD
      - TAXR
      - CBTV
      - ELEC
      - GASB
      - PHON
      - UBIL
      - WTER
      - GAMB
      - LOTT
      - PCOM
      - PDEP
      - PLDS
      - PLRF
    CategoryPurposeCodeV6:
      description: Broader nature of the payment, as published in an external Category Purpose Code list.
      type: string
      enum:
      - BONU
      - CASH
      - CBLK
      - CCRD
      - CORT
      - DCRD
      - DIVI
      - DVPM
      - FCOL
      - GP2P
      - GOVT
      - HEDG
      - INTC
      - INTE
      - LOAN
      - MP2P
      - OTHR
      - PENS
      - RRCT
      - SALA
      - SECU
      - SSBE
      - SUPP
      - TAXS
      - TRAD
      - TREA
      - VATX
      - WHLD
    ApiHeadersSchema_DigitalSignatureType:
      description: The digital signature generated by the API consumer
      type: string
    AccountIdentificationOtherDtoV6:
      required:
      - schemeName
      - identification
      type: object
      properties:
        schemeName:
          description: 'Name of the identification scheme used to identify the account. Permitted values: BBan (basic bank account number) or SortcodeAccountNumber (UK sort code and account number format).'
          type: string
          enum:
          - BBan
          - SortcodeAccountNumber
          example: SortcodeAccountNumber
        identification:
          description: Unambiguous identification for the given scheme (specified in schemeName). For SortcodeAccountNumber, provide the sort code and account number separated by a hyphen (e.g., 040004-12345678).
          type: string
          example: 040004-12345678
          minLength: 1
          maxLength: 34
      additionalProperties: false
    AccountIdentificationIbanDtoV6:
      required:
      - iban
      type: object
      properties:
        iban:
          description: International Bank Account Number (IBAN) - identifier used internationally by financial institutions to uniquely identify the account of a customer. Further specifications of the format and content of the IBAN can be found in the standard ISO 13616 "Banking and related financial services - International Bank Account Number (IBAN)" version 1997-10-01, or later revisions.
          type: string
          pattern: '[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}'
          maxLength: 34
          example: GB29NWBK60161331926819
          minLength: 1
      additionalProperties: false
    ApiHeadersSchema_AuthorizationType:
      description: Authorization header restricted to Bearer token only
      type: string
      pattern: ^Bearer +.+
    InterBankSettlementAmountDtoV6:
      required:
      - amount
      - currency
      type: object
      description: A number of monetary units specified in an active or a historic currency where the unit of currency is explicit and compliant with ISO 4217.
      properties:
        amount:
          type: number
          format: decimal
          example: 1000
          description: Amount of money to be moved between the debtor and creditor expressed in GBP as ordered by the initiating party.
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          example: GBP
          description: Set to 'GBP' as other currencies are not supported.
          minLength: 1
      additionalProperties: false
    CreateInstitutionPaymentDtoV6:
      required:
      - instructionIdentification
      - endToEndIdentification
      - interBankSettlementAmount
      - sourceAccount
      - debtor
      - creditorAccount
      - creditor
      - purpose
      - categoryPurpose
      type: object
      properties:
        instructionIdentification:
          description: 'Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction.


            Usage: The instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction.'
          type: string
          pattern: ^[0-9a-zA-Z/\-\?:\(\)\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$
          minLength: 1
          maxLength: 35
          example: INSTR-001
        endToEndIdentification:
          description: 'Unique identification, as assigned by the initiating party, to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.


            Usage: The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction.


            Usage: In case there are technical limitations to pass on multiple references, the end-to-end identification must be passed on throughout the entire end-to-end chain.'
          type: string
          pattern: ^[0-9a-zA-Z/\-\?:\(\)\.,'\+ ]+$
          minLength: 1
          maxLength: 35
          example: E2E-001
        interBankSettlementAmount:
          $ref: '#/components/schemas/InterBankSettlementAmountDtoV6'
          type: object
        sourceAccount:
          type: object
          oneOf:
          - $ref: '#/components/schemas/AccountIdentificationIbanDtoV6'
          - $ref: '#/components/schemas/AccountIdentificationOtherDtoV6'
          description: The ClearBank account that will be credited or debited based on the successful completion of the payment instruction.
        debtor:
          $ref: '#/components/schemas/PartyDetailsDtoV6'
          description: Party that owes an amount of money to the (ultimate) creditor.
          type: object
        creditorAccount:
          type: object
          description: Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.
          oneOf:
          - $ref: '#/components/schemas/AccountIdentificationIbanDtoV6'
          - $ref: '#/components/schemas/AccountIdentificationOtherDtoV6'
        creditor:
          $ref: '#/components/schemas/PartyDetailsDtoV6'
          description: Party that is owed an amount of money as the (ultimate) creditor.
          type: object
        purpose:
          $ref: '#/components/schemas/PurposeCodeV6'
          description: Underlying reason for the payment transaction, as published in an external Purpose Code list.
          example: INTC
          minLength: 4
          maxLength: 4
        categoryPurpose:
          $ref: '#/components/schemas/CategoryPurposeCodeV6'
          description: Broader nature of the payment, as published in an external Category Purpose Code list.
          example: INTC
          minLength: 4
          maxLength: 4
        remittanceInformation:
          $ref: '#/components/schemas/UnstructuredRemittanceInformationDtoV6'
          type: object
      additionalProperties: false
    ApiHeadersSchema_CorrelationIdentifierType:
      description: A unique identifier generated by ClearBank®
      type: string
    PaymentCreatedResponseDtoV6:
      required:
      - paymentId
      type: object
      properties:
        paymentId:
          $ref: '#/components/schemas/ClearBankSchema_PaymentId'
      additionalProperties: false
      description: ClearBank identifier that uniquely identifies the new outbound/return payment instruction.
    ApiHeadersSchema_RequestIdentifierType:
      description: The request identifier supplied by the API consumer
      type: string
    PartyAddressDetailsDtoV6:
      required:
      - townName
      - country
      - postCode
      type: object
      properties:
        buildingNumber:
          description: Number that identifies the position of a building on a street.
          type: string
          minLength: 1
          maxLength: 16
          pattern: ^[0-9a-zA-Z/\-\?:\(\)\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$
          example: '12'
        buildingName:
          description: Name of the building or house.
          type: string
          minLength: 1
          maxLength: 35
          pattern: ^[0-9a-zA-Z/\-\?:\(\)\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$
          example: ClearBank House
        streetName:
          description: Name of a street or thoroughfare.
          type: string
          minLength: 1
          maxLength: 70
          pattern: ^[0-9a-zA-Z/\-\?:\(\)\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$
          example: Example Street
        townName:
          description: Name of a built-up area, with defined boundaries, and a local government.
          type: string
          minLength: 1
          maxLength: 35
          pattern: ^[0-9a-zA-Z/\-\?:\(\)\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$
          example: London
        country:
          description: Nation with its own government.
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Z]{2}$
          example: GB
        postCode:
          description: Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.
          type: string
          minLength: 1
          maxLength: 16
          pattern: ^[0-9a-zA-Z/\-\?:\(\)\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$
          example: EC2V 8RT
      additionalProperties: false
  parameters:
    ParametersOpenapi_DigitalSignature:
      name: DigitalSignature
      in: header
      description: Signed hash of the body of the request. The hash is signed by your private key.
      required: true
      schema:
        $ref: '#/components/schemas/ApiHeadersSchema_DigitalSignatureType'
    ParametersOpenapi_RequestIdentifier:
      name: X-Request-Id
      in: header
      description: A unique identifier for the request; valid for 24 hours, max length 83.
      required: true
      schema:
        $ref: '#/components/schemas/ApiHeadersSchema_RequestIdentifierType'
    ParametersOpenapi_Authorization:
      name: Authorization
      in: header
      description: Your API token, retrieved from the ClearBank Portal.
      required: true
      schema:
        $ref: '#/components/schemas/ApiHeadersSchema_AuthorizationType'
  headers:
    HeadersOpenapi_CorrelationIdentifier:
      description: A unique identifier generated by ClearBank® for the request. It is recommended you store this response header for debugging purposes
      schema:
        $ref: '#/components/schemas/ApiHeadersSchema_CorrelationIdentifierType'