ClearBank Fps Payments API

openapi: 3.2.0
info:
  title: FI Initiation API 3.0 Fps Payments API
  description: FI Initiation API
  version: 3.0.FPS-payment
tags:
- name: FpsPayments
paths:
  /v3/payments/fps:
    post:
      tags:
      - FpsPayments
      summary: Initiate a payment using the faster payments scheme. This endpoint is FTR compliant.
      description: "This endpoint works on a partial acceptance basis - meaning that you can submit 10 payments and only 6 of them may be accepted for processing.\n            \nEach payment instruction is validated against the scheme specific rules as well as the ISO20022 specification.\n            \nCurrently, only payments through GBP are supported. We have listed possible currencies for future proofing of the API.\n            \nThe remittance information must be scheme compatible. Values exceeding the length limits of the scheme will be truncated. Missing remittance information will be replaced by a blank string."
      operationId: Post
      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:
        description: Information that should be used to create a batch credit transfer.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateCreditTransferRequest'
        x-bodyName: request
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCreditTransferResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtherProblemDetails'
        '404':
          description: Not Found
        '422':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
  /v3/payments/fps/return:
    post:
      tags:
      - FpsPayments
      summary: Return an inbound Faster Payment. This endpoint can be used to return Faster Payments - including Faster Payments Originating Overseas - that cleared less than 90 days ago.
      description: This endpoint is the recommended method for returning Faster Payments that cannot be completed for any reason.
      operationId: PostReturn
      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:
        description: Information that should be used to create an FPS return.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReturnCreditTransferRequest'
        x-bodyName: request
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '422':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
components:
  schemas:
    CounterpartAccountGenericIdentificationScheme:
      type: object
      properties:
        code:
          enum:
          - BBAN
          - CUID
          - UPIC
          type:
          - string
          - 'null'
          description: Name of the identification scheme in coded form. No need to specify if you are providing this information in free-form text in the "proprietary" field.
        proprietary:
          maxLength: 35
          minLength: 0
          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., in the "code" field).
          example: Example scheme
      additionalProperties: false
      description: Information about the identification scheme in coded form or free-form text.
    PaymentInstructionResponse:
      required:
      - endToEndIdentification
      - response
      type: object
      properties:
        endToEndIdentification:
          type: string
          description: Unique identification, as assigned by the initiating party to unambiguously identify the transaction.
          example: E2E12345
        response:
          enum:
          - Accepted
          - InsufficientFunds
          - InvalidAccount
          - InvalidCurrency
          - Rejected
          - DebitPaymentDisabled
          - InvalidInstructionIdentification
          type: string
          description: The result of how the payment instruction has been processed.
          example: Accepted
      additionalProperties: false
      description: The acceptance or rejection status of a payment instruction.
    BatchCreateCreditTransferRequest:
      required:
      - paymentInstructions
      type: object
      properties:
        paymentInstructions:
          type: array
          maxLength: 10
          minLength: 1
          items:
            $ref: '#/components/schemas/BatchPaymentInstruction'
          description: Details of the payments to be made.
      additionalProperties: false
      description: Information that should be used to create a batch credit transfer.
    BatchStructured:
      type: object
      properties:
        creditorReferenceInformation:
          $ref: '#/components/schemas/BatchCreditorReferenceInformation'
          description: Reference information provided by the debtor to allow the identification of underlying documents by the creditor.
      additionalProperties: false
      description: Information supplied by the remitter (in a structured form), to reconcile an entry with item(s) that the payment intends to settle (for example, a purchase reference number).
    HalLink:
      required:
      - href
      - name
      type: object
      properties:
        name:
          type: string
          description: The named link type.
        href:
          type: string
          description: URI to be used.
        templated:
          type: boolean
          description: Specifies "true" if href is a URI template, i.e., with parameters. Otherwise, this property is absent or set to false.
      additionalProperties: false
      description: Hypermedia link.
    BatchRemittanceInformation:
      type: object
      properties:
        structured:
          $ref: '#/components/schemas/BatchStructured'
          description: Information supplied by the remitter (in a structured form), to reconcile an entry with item(s) that the payment intends to settle (e.g., a purchase reference number).
        unstructured:
          $ref: '#/components/schemas/BatchUnstructured'
          description: Information supplied by the remitter (in an unstructured form) to reconcile an entry with item(s) that the payment intends to settle.
      additionalProperties: false
      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.
    ValidationProblemDetails:
      type: object
      properties:
        errors:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            items:
              type: string
          description: The validation errors.
          example:
            field1:
            - Error message 1
            field2:
            - Error message 2
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provides human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".
          example: https://example.com/probs/error-code
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It should not change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see[RFC7231], Section 3.4).
          example: Error title
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
          example: 400
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
          example: The request is invalid. See errors for details.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
          example: /errors/12345
      additionalProperties: {}
      description: A machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807
    BatchCreditorPartyIdentifier:
      required:
      - name
      type: object
      properties:
        name:
          maxLength: 140
          minLength: 1
          type: string
          description: The name of the account holder.
          example: Aisha Khan
        legalEntityIndentifier:
          maxLength: 35
          minLength: 0
          type:
          - string
          - 'null'
          description: 'The legal entity identifier of the account holder (eg: charity number). This should be supplied if known.'
          example: 9485839XYZ
      additionalProperties: false
      description: The name and, optionally, the legal entity identifier of the account.
    BatchPaymentInstructionCounterpartAccount:
      required:
      - identification
      type: object
      properties:
        identification:
          $ref: '#/components/schemas/BatchPaymentInstructionCounterpartAccountIdentification'
          description: The identifiable information of an account.
      additionalProperties: false
      description: Information about the counterpart in a given transaction.
    BatchCreditTransferResponse:
      type: object
      properties:
        transactions:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PaymentInstructionResponse'
          description: An array containing the the acceptance or rejection status of each individual payment instruction. You'll receive a 400 - Bad Request response if all payments in the batch fail. You'll receive a 202 - Accepted response if any payments in the batch succeed.
        halLinks:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/HalLink'
          description: Hypermedia links.
      additionalProperties: false
      description: The result of each payment instruction and applicable links
    BatchCreditorReferenceInformation:
      type: object
      properties:
        reference:
          maxLength: 35
          minLength: 0
          type:
          - string
          - 'null'
          description: A reference, as assigned by the debtor to unambiguously refer to the payment transaction. Conditionally required if supplied by the debtor.
          example: Payment for invoice 12345
      additionalProperties: false
      description: Reference information provided by the ultimate debtor to allow the identification of underlying documents by the creditor.
    CreateReturnCreditTransferRequest:
      required:
      - paymentReturnInstruction
      type: object
      properties:
        paymentReturnInstruction:
          $ref: '#/components/schemas/PaymentReturnInstruction'
          description: Information about the payment return.
      additionalProperties: false
      description: Information that should be used to create a single credit return.
    PaymentReturnInstruction:
      required:
      - TransactionId
      - ReasonForReturn
      type: object
      properties:
        TransactionId:
          maxLength: 36
          minLength: 1
          type: string
          description: The ID of the transaction to be returned.
          format: uuid
        ReasonForReturn:
          type: string
          description: 'A scheme compliant return code. Accepted values: [ BeneficiarySortCodeOrAccountUnknown, BeneficiaryAccountClosed, BeneficiaryAccountStopped, BeneficiaryDeceased, AccountCannotBeIdentified, BeneficiaryAccountNameDoesNotMatchBeneficiaryAccountNumber, ReturnRequestedBySenderOfOriginalPayment, AccountIsNotInCurrencyQuoted, BeneficiaryNotExpectingFundsOrInstructedReturn, TermsAndConditionsOfAccountDoNotPermitCreditingOfFunds, SendingFpsInstitutionActionRequired, AccountTransferred, PaymentCannotBeAppliedBecauseOfBeneficiarySensitivities, Other ]'
      additionalProperties: false
      description: Information about the single payment return instruction.
    BatchCreditTransfer:
      required:
      - amount
      - creditor
      - creditorAccount
      - paymentIdentification
      - remittanceInformation
      type: object
      properties:
        paymentIdentification:
          $ref: '#/components/schemas/BatchPaymentIdentification'
          description: Identification of the payment instruction.
        amount:
          $ref: '#/components/schemas/BatchAmount'
          description: Indicates the amount and the currency used in a given transaction or account balance.
        creditor:
          $ref: '#/components/schemas/BatchCreditorPartyIdentifier'
          description: The name and, optionally, the legal entity identifier of the account.
        creditorAccount:
          $ref: '#/components/schemas/BatchPaymentInstructionCounterpartAccount'
          description: Information about the counterpart in a given transaction.
        remittanceInformation:
          $ref: '#/components/schemas/BatchRemittanceInformation'
          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.
        enforceSendToScheme:
          type: boolean
          description: If set to true, then the payment will be sent to scheme for processing. If set to false or not supplied, then it will be processed as an internal transfer if eligible.
      additionalProperties: false
      description: Represents a creditor in a payment instruction.
    OtherProblemDetails:
      type: object
      properties:
        transactions:
          type:
          - array
          - 'null'
          items:
            type: object
            properties:
              endToEndIdentification:
                type: string
                example: E2E12345
                description: Unique identification, as assigned by the initiating party to unambiguously identify the transaction.
              response:
                description: Indicates the reason for the rejection of the payment instruction.
                enum:
                - Accepted
                - InsufficientFunds
                - InvalidAccount
                - InvalidCurrency
                - Rejected
                - DebitPaymentDisabled
                - InvalidInstructionIdentification
                type: string
                example: InsufficientFunds
          description: If all payments in the batch fail, you'll receive a 400 response containing this array in the body, with an entry for each failed payment. You'll receive a 202 - Accepted response if any payments in the batch succeed. The model for 400 responses will match the model of 422 - Client Error in all other cases.
      additionalProperties: false
    BatchAmount:
      required:
      - instructedAmount
      type: object
      properties:
        currency:
          enum:
          - ALL
          - DZD
          - ARS
          - AUD
          - BSD
          - BHD
          - BDT
          - AMD
          - BBD
          - BMD
          - BTN
          - BOB
          - BWP
          - BZD
          - SBD
          - BND
          - MMK
          - BIF
          - KHR
          - CAD
          - CVE
          - KYD
          - LKR
          - CLP
          - CNY
          - COP
          - KMF
          - CRC
          - HRK
          - CUP
          - CZK
          - DKK
          - DOP
          - SVC
          - ETB
          - ERN
          - FKP
          - FJD
          - DJF
          - GMD
          - GIP
          - GTQ
          - GNF
          - GYD
          - HTG
          - HNL
          - HKD
          - HUF
          - ISK
          - INR
          - IDR
          - IRR
          - IQD
          - ILS
          - JMD
          - JPY
          - KZT
          - JOD
          - KES
          - KPW
          - KRW
          - KWD
          - KGS
          - LAK
          - LBP
          - LSL
          - LRD
          - LYD
          - MOP
          - MWK
          - MYR
          - MVR
          - MUR
          - MXN
          - MNT
          - MDL
          - MAD
          - OMR
          - NAD
          - NPR
          - ANG
          - AWG
          - VUV
          - NZD
          - NIO
          - NGN
          - NOK
          - PKR
          - PAB
          - PGK
          - PYG
          - PEN
          - PHP
          - QAR
          - RUB
          - RWF
          - SHP
          - SAR
          - SCR
          - SLL
          - SGD
          - VND
          - SOS
          - ZAR
          - SSP
          - SZL
          - SEK
          - CHF
          - SYP
          - THB
          - TOP
          - TTD
          - AED
          - TND
          - UGX
          - MKD
          - EGP
          - GBP
          - TZS
          - USD
          - UYU
          - UZS
          - WST
          - YER
          - TWD
          - MRU
          - STN
          - CUC
          - ZWL
          - BYN
          - TMT
          - GHS
          - VEF
          - SDG
          - UYI
          - RSD
          - MZN
          - AZN
          - RON
          - CHE
          - CHW
          - TRY
          - XAF
          - XCD
          - XOF
          - XPF
          - XBA
          - XBB
          - XBC
          - XBD
          - XAU
          - XDR
          - XAG
          - XPT
          - XTS
          - XPD
          - XUA
          - ZMW
          - SRD
          - MGA
          - COU
          - AFN
          - TJS
          - AOA
          - BGN
          - CDF
          - BAM
          - EUR
          - MXV
          - UAH
          - GEL
          - BOV
          - PLN
          - BRL
          - CLF
          - XSU
          - USN
          - XXX
          type:
          - string
          - 'null'
          example: GBP
          description: Set to 'GBP' as other currencies are not supported.
        instructedAmount:
          type: number
          description: Amount of funds to be moved between the debtor and creditor (prior to deduction of charges) in GBP.
          format: double
          example: 100.0
      additionalProperties: false
      description: Indicates the amount and the currency used in a given transaction or account balance.
    BatchDebtorPartyIdentifier:
      required:
      - address
      type: object
      properties:
        legalEntityIdentifier:
          maxLength: 35
          minLength: 0
          type:
          - string
          - 'null'
          description: 'The legal entity identifier of the account holder (eg: charity number). This should be supplied if known.'
          example: 9485839XYZ
        address:
          maxLength: 140
          minLength: 1
          pattern: ^[a-zA-Z0-9\/\-?:().,'+ ]*$
          type: string
          description: 'The full postal address of the account holder. For UK addresses, the order of this information MUST be: country, town, city, state/province/municipality, street name, building number and/or name, postal code.'
          example: UK, Manchester, Greater Manchester, Oxford Road, 123, M13 9PL
      additionalProperties: false
      description: 'Optionally, the Legal Entity Identifier of the account.

        Mandatory the Address of the account.'
    BatchCounterpartAccountGenericIdentification:
      required:
      - identification
      - schemeName
      type: object
      properties:
        issuer:
          maxLength: 35
          minLength: 0
          type:
          - string
          - 'null'
          description: The name of the entity that assigns the identification.
          example: Example Passport
        identification:
          maxLength: 34
          minLength: 1
          type: string
          description: Identification assigned by an institution.
          example: '123456789012345678'
        schemeName:
          $ref: '#/components/schemas/CounterpartAccountGenericIdentificationScheme'
          description: Name of the identification scheme.
      additionalProperties: false
      description: Unique identification of an account, as assigned by the account servicer, using an identification scheme.
    BatchUnstructured:
      type: object
      properties:
        additionalReferenceInformation:
          $ref: '#/components/schemas/BatchAdditionalReferenceInformation'
          description: Additional unstructured remittance information.
      additionalProperties: false
      description: Information supplied by the remitter (in a structured form), to reconcile an entry with item(s) that the payment intends to settle (for example, a purchase reference number).
    BatchAdditionalReferenceInformation:
      type: object
      properties:
        reference:
          maxLength: 140
          minLength: 0
          type:
          - string
          - 'null'
          description: Additional remittance information.
          example: Plumbing payment
      additionalProperties: false
      description: Reference information provided by the ultimate debtor to allow the identification of underlying documents by the creditor.
    BatchPaymentIdentification:
      required:
      - endToEndIdentification
      - instructionIdentification
      type: object
      properties:
        instructionIdentification:
          maxLength: 35
          minLength: 1
          type: string
          description: Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction.
          example: PAYMENT12345
        endToEndIdentification:
          maxLength: 35
          minLength: 1
          type: string
          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.
          example: E2E12345
      additionalProperties: false
      description: Identification of the payment instruction.
    BatchPaymentInstructionCounterpartAccountIdentification:
      type: object
      properties:
        iban:
          type:
          - string
          - 'null'
          description: The International Bank Account Number of the account.
          example: GB29NWBK60161331926819
        other:
          $ref: '#/components/schemas/BatchCounterpartAccountGenericIdentification'
          description: Unique identification of an account, as assigned by the account servicer, using an identification scheme.
      additionalProperties: false
      description: The identifiable information of an account.
    BatchPaymentInstruction:
      required:
      - creditTransfers
      - debtor
      - debtorAccount
      - paymentInstructionIdentification
      type: object
      properties:
        debtor:
          $ref: '#/components/schemas/BatchDebtorPartyIdentifier'
          description: Details about the account holder.
        paymentInstructionIdentification:
          maxLength: 35
          minLength: 1
          type: string
          description: The unique identifier for the payment instruction.
          example: INSTRUCTION12345
        paymentTypeCode:
          type: string
          maxLength: 3
          minLength: 3
          description: A three-letter code signifying the type of payment. SIP - Single immediate payment, SOP - Standing order payment, FDP - Forward-dated payment.
          enum:
          - SIP
          - SOP
          - FDP
        debtorAccount:
          $ref: '#/components/schemas/BatchPaymentInstructionCounterpartAccount'
          description: Information about the counterpart in a given transaction.
        creditTransfers:
          type: array
          maxLength: 10
          minLength: 1
          items:
            $ref: '#/components/schemas/BatchCreditTransfer'
          description: A series of payments that should be made from the debtor account.
      additionalProperties: false
      description: A payment from a single account to multiple creditors.