ClearBank Payments API

openapi: 3.2.0
info:
  title: Mccy Payment Orchestrator External Api V1 Payments API
  description: Mccy Payment Orchestrator External Api V1
  version: 1.0.Dec21
tags:
- name: Payments
paths:
  /v1/mccy/payments:
    post:
      tags:
      - Payments
      summary: This endpoint is used to initiate payments.
      parameters:
      - name: Authorization
        in: header
        description: Your API token, obtained from the ClearBank Portal.
        required: true
        schema:
          type: string
      - name: DigitalSignature
        in: header
        description: Signed hash of the body of the request. The hash is signed by your private key.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request; valid for 24 hours, max length 83.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '202':
          description: Accepted
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '406':
          description: Not Acceptable
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Conflict
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Unprocessable Entity
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server Error
        '503':
          description: Server Error
  /v1/mccy/payments/{batchId}:
    delete:
      tags:
      - Payments
      summary: This endpoint is used to cancel an entire batch of payments with a matching batch ID. It must be sent at least one hour prior to the opening of the currency payment window in order to successfully cancel the payment.
      parameters:
      - name: Authorization
        in: header
        description: Your API token, obtained from the ClearBank Portal.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request; valid for 24 hours, max length 83.
        required: true
        schema:
          type: string
      - name: batchId
        in: path
        required: true
        description: This must match the batch ID submitted in the payment request.
        schema:
          type: string
      responses:
        '204':
          description: Success
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '406':
          description: Not Acceptable
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Client Error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server Error
        '503':
          description: Server Error
  /v1/mccy/payments/{batchId}/{endToEndId}:
    delete:
      tags:
      - Payments
      summary: This endpoint is used to cancel a single payment within a batch, with a matching batch ID and end-to-end ID. It must be sent at least one hour prior to the opening of the currency payment window in order to successfully cancel the payment.
      parameters:
      - name: Authorization
        in: header
        description: Your API token, obtained from the ClearBank Portal.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request; valid for 24 hours, max length 83.
        required: true
        schema:
          type: string
      - name: batchId
        in: path
        required: true
        description: This must match the batch ID submitted in the payment request.
        schema:
          type: string
      - name: endToEndId
        in: path
        required: true
        description: This must match the end-to-end ID submitted in the payment request.
        schema:
          type: string
          pattern: '[A-Za-z0-9/\-?:.,"+ ]'
      responses:
        '204':
          description: Success
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '406':
          description: Not Acceptable
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Client Error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server Error
        '503':
          description: Server Error
components:
  schemas:
    PaymentRequestItem:
      required:
      - endToEndId
      - reference
      - accountIdentifier
      - amount
      - debtorAddress
      - creditor
      - debtorAccountCurrency
      - debtorName
      type: object
      properties:
        endToEndId:
          type: string
          description: Unique identifier provided to ClearBank for each payment.
          minLength: 1
          maxLength: 35
          pattern: '[A-Za-z0-9/\-?:.,"+ ]'
          example: pd0G4d9XCLOzpM5lBA86YNXU8KU3I0etZ5T
        reference:
          type: string
          description: Reference provided by the debtor for the payment.
          minLength: 1
          maxLength: 140
          example: Human readable example text
        amount:
          type: number
          description: Instructed payment amount in the batch's specified currency.
          minimum: 0.01
          maximum: 999999999.99
          multipleOf: 0.01
          example: 1234.56
        creditor:
          $ref: '#/components/schemas/Creditor'
        debtorName:
          type: string
          description: The name used to identify the legal owner of the account from which the funds will be debited.
          minLength: 1
          maxLength: 140
          example: Bradley Kennedy
        debtorAddress:
          type: object
          description: Information about the debtor's address.
          required:
          - addressLine1
          - addressLine2
          - postCode
          - country
          properties:
            addressLine1:
              type: string
              minLength: 1
              maxLength: 70
              description: First line of the debtor's address.
              example: Green House
            addressLine2:
              type: string
              minLength: 1
              maxLength: 35
              description: Second line of the debtor's address.
              example: Purple Lane
            addressLine3:
              type:
              - string
              - 'null'
              minLength: 0
              maxLength: 35
              description: Third line of the debtor's address.
              example: Orange District
            postCode:
              type: string
              minLength: 1
              maxLength: 16
              description: Debtor's postcode.
              example: CB2 5AB
            country:
              minLength: 2
              maxLength: 2
              type: string
              description: Two-letter ISO country code for the debtor's address.
              pattern: ^[A-Z]{2}$
              example: GB
        debtorBic:
          type:
          - string
          - 'null'
          description: Debtor's Business Identifier Code (BIC).
          minLength: 8
          maxLength: 11
          pattern: '[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}'
          example: ABCDNLAA123
        debtorPrivateIdentification:
          type: object
          description: The debtor's private or personal information.
          properties:
            dateAndPlaceOfBirth:
              type: object
              description: Debtor's birth information.
              properties:
                dateOfBirth:
                  type:
                  - string
                  - 'null'
                  description: Debtor's date of birth.
                  format: date
                  example: '1962-02-21'
                cityOfBirth:
                  type:
                  - string
                  - 'null'
                  description: Debtor's city of birth.
                  minLength: 0
                  maxLength: 35
                  example: Paris
                countryOfBirth:
                  type:
                  - string
                  - 'null'
                  description: Two-letter ISO country code for the debtor's country of birth.
                  minLength: 0
                  maxLength: 2
                  pattern: ^[A-Z]{2}$
                  example: France
            other:
              type: object
              description: Information about the debtor's private identification.
              properties:
                identification:
                  type:
                  - string
                  - 'null'
                  description: Debtor's personal identification, as assigned by an identification scheme.
                  minLength: 0
                  maxLength: 35
                schemeName:
                  type: object
                  description: Information about the identification scheme in coded form or free-form text.
                  properties:
                    code:
                      type:
                      - string
                      - 'null'
                      description: Name of the identification scheme in coded form, as specified in the ExternalPersonIdentification1Code code set required by ISO 20022 Message Schemas. No need to specify if you are providing this name in free-form text (i.e., proprietary).
                      minLength: 0
                      maxLength: 4
                      example: CCPT
                    proprietary:
                      type:
                      - string
                      - 'null'
                      description: Name of the identification scheme in free-form text. No need to specify if you are providing this name in coded form (i.e., code).
                      minLength: 0
                      maxLength: 35
                      example: Other identification scheme name
        accountIdentifier:
          $ref: '#/components/schemas/AccountIdentifier'
        debtorAccountCurrency:
          type: string
          description: Three-letter ISO currency code for the currency supported by the debtor account.  This field is case insensitive.
          minLength: 3
          maxLength: 3
          enum:
          - EUR
          - USD
          - CAD
          - CHF
          - CZK
          - DKK
          - HUF
          - NOK
          - PLN
          - RON
          - SEK
          example: EUR
        intermediaryAgent:
          $ref: '#/components/schemas/IntermediaryAgent'
        creditorAgent:
          $ref: '#/components/schemas/CreditorAgent'
        instructionForDebtorAgent:
          type:
          - string
          - 'null'
          description: Further information related to the processing of the payment instruction that may need to be acted upon by the debtor agent (depending on an agreement between the debtor and debtor agent). Financial institutions sending payments on behalf of their customers should populate their BIC in this field preceded by '/INST/' signifying that they are the instructing institution.
          minLength: 0
          maxLength: 140
          example: Example further instruction text
        purpose:
          $ref: '#/components/schemas/Purpose'
        remittanceInformation:
          $ref: '#/components/schemas/RemittanceInformation'
        ultimateCreditor:
          $ref: '#/components/schemas/UltimateCreditor'
      additionalProperties: false
    Purpose:
      type:
      - object
      - 'null'
      description: Information about the purpose of the transaction.
      properties:
        code:
          type:
          - string
          - 'null'
          description: Purpose of the transaction in coded form, as specified in the Purpose1Code code set required by ISO 20022 Message Schemas. No need to specify if you are providing this name in free-form text (i.e., proprietary).
          minLength: 0
          maxLength: 4
          example: SUPP
        proprietary:
          type:
          - string
          - 'null'
          description: Purpose of the transaction in free-form text. No need to specify if you are providing this name in  coded form (i.e., code).
          minLength: 0
          maxLength: 35
          example: Other non-codified purpose
      additionalProperties: false
    PaymentResponse:
      type: object
      properties:
        isScheduled:
          type: boolean
          description: Whether the payment(s) are scheduled for the next payment window.
          example: true
      additionalProperties: false
    AccountIdentifier:
      required:
      - kind
      - identifier
      type: object
      description: The unique identifier for the account.
      properties:
        kind:
          $ref: '#/components/schemas/AccountIdentifierKind'
        identifier:
          type: string
          description: Unique account identifier value that corresponds to the specified account identifier kind.
          minLength: 1
          maxLength: 36
          example: GB22CBUK60109839856819
      additionalProperties: false
    RemittanceInformation:
      type:
      - object
      - 'null'
      description: Remittance information to accompany the payment.
      properties:
        additionalRemittanceInformation:
          type:
          - string
          - 'null'
          description: Additional remittance information in free-form text, to compliment the structured remittance information.
          minLength: 0
          maxLength: 140
          example: Example unstructured information
      additionalProperties: false
    PaymentRequest:
      required:
      - currencyCode
      - transactions
      type: object
      properties:
        batchId:
          type:
          - string
          - 'null'
          description: Unique identifier for the batch in which the payment is being submitted. (GUID format 128-bit label). You must set a batch ID to be able to cancel a payment.
          format: uuid
          example: d7cc6fda-52a5-5ba8-a03e-303746dc2501
        currencyCode:
          type: string
          description: Three-letter ISO currency code for the outbound payment. This field is case insensitive.
          example: EUR
          minLength: 3
          maxLength: 3
          enum:
          - EUR
          - USD
          - CAD
          - CHF
          - CZK
          - DKK
          - HUF
          - NOK
          - PLN
          - RON
          - SEK
        transactions:
          type: array
          description: Array of transactions. The maximum batch size is 100.
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/PaymentRequestItem'
      additionalProperties: false
    Creditor:
      required:
      - name
      - address
      type: object
      description: Information about the creditor of the transaction.
      properties:
        name:
          type: string
          description: Creditor's name.
          minLength: 1
          maxLength: 140
          example: Newell Saunders
        address:
          type: object
          description: Information about the creditor's address.
          required:
          - addressLine1
          - addressLine2
          - postCode
          - country
          properties:
            addressLine1:
              type: string
              minLength: 1
              maxLength: 70
              description: First line of the creditor's address.
              example: 123A
            addressLine2:
              type: string
              minLength: 1
              maxLength: 35
              description: Second line of the creditor's address.
              example: Wren Way
            addressLine3:
              type:
              - string
              - 'null'
              minLength: 0
              maxLength: 35
              description: Third line of the creditor's address.
              example: Hamlinton
            postCode:
              type: string
              minLength: 1
              maxLength: 16
              description: Creditor's postcode.
              example: NN87 2335
            country:
              minLength: 2
              maxLength: 2
              type: string
              description: Two-letter ISO country code for the creditor's address.
              pattern: ^[A-Z]{2}$
              example: PT
        bic:
          type:
          - string
          - 'null'
          description: Creditor's Business Identifier Code (BIC).
          minLength: 8
          maxLength: 11
          pattern: '[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}'
          example: 1A2BPT12AB3
        identification:
          type: object
          description: Creditor's business and personal information.
          properties:
            organisationIdentification:
              type: object
              description: Information about the creditor's organisation.
              properties:
                Other:
                  type: object
                  description: Information about the creditor's non-SWIFT BIC organisation identification.
                  properties:
                    identification:
                      type:
                      - string
                      - 'null'
                      description: Creditor's non-SWIFT BIC organisation identification, as assigned by an identification scheme.
                      minLength: 0
                      maxLength: 35
                    schemeName:
                      type: object
                      description: Information about the organisation identification scheme in coded form or free-form text.
                      properties:
                        code:
                          type:
                          - string
                          - 'null'
                          description: Name of the identification scheme in coded form, as specified in the ExternalOrganisationIdentification1Code code set required by ISO 20022 Message Schemas. No need to specify if you are providing this name in free-form text (i.e., proprietary).
                          minLength: 0
                          maxLength: 4
                          example: BDID
                        proprietary:
                          type:
                          - string
                          - 'null'
                          description: Name of the identification scheme in free-form text. No need to specify if you are providing this name in  coded form (i.e., code).
                          minLength: 0
                          maxLength: 35
                          example: Other identification scheme name
                    issuer:
                      type:
                      - string
                      - 'null'
                      description: Entity/authority/body responsible for issuing the identification.
                      minLength: 0
                      maxLength: 35
                      example: Identification authority name
            privateIdentification:
              type: object
              description: The creditor's private or personal information.
              properties:
                dateAndPlaceOfBirth:
                  type: object
                  description: Creditor's birth information.
                  properties:
                    dateOfBirth:
                      type:
                      - string
                      - 'null'
                      description: Creditor's date of birth.
                      format: date
                      example: '1995-12-27'
                    cityOfBirth:
                      type:
                      - string
                      - 'null'
                      description: Creditor's city of birth.
                      minLength: 0
                      maxLength: 35
                      example: Lisbon
                    countryOfBirth:
                      type:
                      - string
                      - 'null'
                      description: Two-letter ISO country code for the creditor's country of birth.
                      minLength: 0
                      maxLength: 2
                      pattern: ^[A-Z]{2}$
                      example: PT
                other:
                  type: object
                  description: Information about the creditor's private identification.
                  properties:
                    identification:
                      type:
                      - string
                      - 'null'
                      description: Creditor's personal identification, as assigned by an identification scheme. For example, their passport number.
                      minLength: 0
                      maxLength: 35
                      example: 020696623
                    schemeName:
                      type: object
                      description: Information about the identification scheme in coded form, or free-form text.
                      properties:
                        code:
                          type:
                          - string
                          - 'null'
                          description: Name of the identification scheme in coded form, as specified in the  ExternalPersonIdentification1Code code set required by ISO 20022 Message Schemas. No need to specify if you are providing this name in free-form text (i.e., proprietary).
                          minLength: 0
                          maxLength: 4
                          example: CCPT
                        proprietary:
                          type:
                          - string
                          - 'null'
                          description: Name of the identification scheme in free-form text. No need to specify if you are providing this name in  coded form (i.e., code).
                          minLength: 0
                          maxLength: 35
                          example: Other identification scheme name
        countryOfResidence:
          type:
          - string
          - 'null'
          description: Two-letter ISO country code for the creditor's country of residence.
          minLength: 0
          maxLength: 2
          pattern: ^[A-Z]{2}$
          example: PT
        contactDetails:
          type: object
          description: Creditor's contact details.
          properties:
            name:
              type:
              - string
              - 'null'
              description: Creditor's contact name.
              minLength: 0
              maxLength: 140
              example: Ryan Christensen
            emailAddress:
              type:
              - string
              - 'null'
              description: Creditor's email address.
              minLength: 0
              maxLength: 2048
              example: tokchri@business.eu
        iban:
          type:
          - string
          - 'null'
          description: Creditor's International Bank Account Number. Mandatory only if account number is not specified.
          example: ES9242020418450222051122
        accountNumber:
          type:
          - string
          - 'null'
          description: Creditor's Account Number. Mandatory only if iban is not specified.
          minLength: 0
          maxLength: 34
          example: '0222051122'
        schemeName:
          type: object
          description: Information about the identification scheme in coded form or free-form text. This should only be provided if the creditor's account number has been specified
          properties:
            code:
              type:
              - string
              - 'null'
              description: 'Name of the identification scheme in coded form. No need to specify if you are providing this name in free-form text (i.e., proprietary). Valid options include: CASH, CHAR, COMM, TAXE, CISH, TRAS, SACC, CACC, SVGS, ONDP, MGLD, NREX, MOMA, LOAN, SLRY, ODFT.'
              minLength: 0
              maxLength: 4
              example: TRAS
            proprietary:
              type:
              - string
              - 'null'
              description: Name of the identification scheme in free-form text. No need to specify if you are providing this name in  coded form (i.e., code).
              minLength: 0
              maxLength: 35
              example: Example other identification scheme
      additionalProperties: false
    IntermediaryAgent:
      type: object
      description: Information about the intermediary/correspondent bank.
      properties:
        FinancialInstitutionIdentification:
          type: object
          description: Information that identifies the intermediary agent as a financial institution. Mandatory only when intermediary agent details are being provided.
          required:
          - addressDetails
          properties:
            bic:
              type:
              - string
              - 'null'
              description: Intermediary agent's Business Identifier Code (BIC). No need to specify if you are providing the intermediary agent's American Bankers Association (ABA) routing number.
              minLength: 8
              maxLength: 11
              pattern: '[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}'
              example: NWBKGB2LXXX
            aba:
              type:
              - string
              - 'null'
              description: Intermediary agent's American Bankers Association (ABA) routing number. No need to specify if you are providing the intermediary agent's Business Identifier Code (BIC).
              minLength: 0
              maxLength: 35
              example: '376582168'
            name:
              type:
              - string
              - 'null'
              description: Intermediary agent's name.
              minLength: 0
              maxLength: 140
              example: Intermediary Agent Financial Institution
            addressDetails:
              type:
              - object
              - 'null'
              description: Information about the intermediary agent's address. Mandatory only when financial institution identification details are being provided.
              required:
              - country
              properties:
                addressLine1:
                  type:
                  - string
                  - 'null'
                  minLength: 0
                  maxLength: 70
                  description: First line of the intermediary agent's address.
                  example: 12 Banking Building
                addressLine2:
                  type:
                  - string
                  - 'null'
                  minLength: 0
                  maxLength: 35
                  description: Second line of the intermediary agent's address.
                  example: Bank Street
                addressLine3:
                  type:
                  - string
                  - 'null'
                  minLength: 0
                  maxLength: 35
                  description: Third line of the intermediary agent's address.
                  example: Belfast
                postCode:
                  type:
                  - string
                  - 'null'
                  minLength: 0
                  maxLength: 16
                  description: Intermediary agent's postcode.
                  example: BT1 5GS
                country:
                  minLength: 2
                  maxLength: 2
                  type: string
                  description: Two-letter ISO country code for the intermediary agent's address. Mandatory only when the intermediary agent's details are being provided.
               

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