ClearBank SCT Payments API

openapi: 3.2.0
info:
  title: ClearBank.Sepa.Ct.Orchestrator.Api SCT Payments API
  version: 1.0-SEPA-CT
tags:
- name: SCT Payments
paths:
  /payments/sepa-ct/v1/customer-payments:
    post:
      tags:
      - SCT Payments
      summary: This endpoint is used to create an outbound SCT payment.
      operationId: Payment.Create
      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/CreateSepaOutboundPaymentRequest'
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSepaOutboundPaymentResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /payments/sepa-ct/v1/recall-response:
    post:
      tags:
      - SCT Payments
      summary: This endpoint is used to approve or reject a recall request of an inbound SCT payment.
      operationId: Payments.Inbound.RecallRequestResult
      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/RecallOfInboundPaymentReviewRequest'
        required: true
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /payments/sepa-ct/v1/recall:
    post:
      tags:
      - SCT Payments
      summary: This endpoint is used to request a recall for an outbound SCT payment.
      operationId: Payment.Recall
      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/RecallOfOutboundPaymentRequest'
        required: true
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /payments/sepa-ct/v1/payment-returns:
    post:
      tags:
      - SCT Payments
      summary: This endpoint is used to return an inbound SCT payment.
      operationId: Payments.Inbound.ReturnOfInboundPayment
      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/ReturnOfInboundPaymentRequest'
        required: true
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    DebtorPostalAddress:
      required:
      - country
      - townName
      type: object
      description: Postal address of the debtor. townName and country are mandatory if the payment originates from or is destined for a country outside the EEA.
      properties:
        streetName:
          maxLength: 70
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type: string
          description: Name of a street or thoroughfare.
          example: My Street
        buildingNumber:
          maxLength: 16
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type:
          - string
          - 'null'
          description: Number that identifies the position of a building on a street.
          example: '1'
        townName:
          maxLength: 35
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type:
          - string
          - 'null'
          description: Name of a built-up area, with defined boundaries, and a local government. Mandatory if the payment origin or destination country is outside the EEA.
          example: London
        postCode:
          maxLength: 16
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type:
          - string
          - 'null'
          description: Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.
          example: XX99 9XX
        countrySubdivision:
          maxLength: 35
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type:
          - string
          - 'null'
          description: Identifies a subdivision of a country such as state, region, county.
          example: London
        country:
          minLength: 1
          pattern: '[A-Z]{2,2}'
          type: string
          description: Nation with its own government. Mandatory if the payment origin or destination country is outside the EEA.
          example: GB
      additionalProperties: false
    CreateSepaOutboundPaymentResponse:
      type: object
      properties:
        paymentId:
          type: string
          maxLength: 36
          format: uuid
          readOnly: true
          example: 1bfb7a86-7d9b-45ff-9d5c-34048efc4c8a
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
        errors:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            items:
              type: string
          readOnly: true
      additionalProperties: {}
    IdentificationCreditor:
      type: object
      properties:
        organisationIdentification:
          $ref: '#/components/schemas/OrganisationIdentificationCreditor'
        privateIdentification:
          $ref: '#/components/schemas/PrivateIdentification'
      additionalProperties: false
    PostalAddress:
      required:
      - country
      - townName
      type: object
      properties:
        streetName:
          maxLength: 70
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type: string
          description: Name of a street or thoroughfare.
          example: My Street
        buildingNumber:
          maxLength: 16
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type:
          - string
          - 'null'
          description: Number that identifies the position of a building on a street.
          example: '1'
        townName:
          maxLength: 35
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type:
          - string
          - 'null'
          description: Name of a built-up area, with defined boundaries, and a local government.
          example: London
        postCode:
          maxLength: 16
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type:
          - string
          - 'null'
          description: Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.
          example: XX99 9XX
        countrySubdivision:
          maxLength: 35
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type:
          - string
          - 'null'
          description: Identifies a subdivision of a country such as state, region, county.
          example: London
        country:
          minLength: 1
          pattern: '[A-Z]{2,2}'
          type: string
          description: Nation with its own government.
          example: GB
      additionalProperties: false
    RecallOfInboundPaymentReviewRequest:
      required:
      - paymentId
      - recallResponseAccepted
      type: object
      properties:
        paymentId:
          pattern: '[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}'
          maxLength: 36
          type: string
          description: Unique identifier of the Inbound SCT payment to be recalled.
          format: uuid
          example: 1bfb7a86-7d9b-45ff-9d5c-34048efc4c8a
        recallResponseAccepted:
          type: boolean
          description: Accept or reject a request for recall of an SCT inbound payment
          example: 'True'
        rejectCode:
          pattern: ^[A-Z0-9]{1,4}$
          minLength: 4
          maxLength: 4
          type:
          - string
          - 'null'
          description: 'Reason code required if recall request is rejected '
          example: CUST
        additionalInfo:
          maxLength: 105
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type:
          - string
          - 'null'
          format: uuid
          description: Additional information
          example: Additional details.
      additionalProperties: false
    PrivateIdentification:
      type: object
      properties:
        dateAndPlaceOfBirth:
          $ref: '#/components/schemas/DateAndPlaceOfBirth'
        other:
          maxLength: 35
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type:
          - string
          - 'null'
          description: Unique identification of a person, as assigned by an institution, using an identification scheme.
          example: Other identification.
      additionalProperties: false
    ReturnOfInboundPaymentRequest:
      required:
      - paymentId
      type: object
      properties:
        paymentId:
          pattern: '[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}'
          maxLength: 36
          type: string
          description: Unique identifier of the payment to be returned.
          format: uuid
          example: b907589a-f3c5-4328-84c5-c83df6f66d07
      additionalProperties: false
    Creditor:
      required:
      - accountIban
      - name
      type: object
      properties:
        name:
          maxLength: 70
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type: string
          description: The name used to identify the legal owner of the account from which to credit funds.
          example: John Doe
        accountIban:
          minLength: 1
          pattern: '[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}'
          type: string
          description: International Bank Account Number (IBAN) - identifier used internationally by financial institutions to uniquely identify the account of a customer.
          example: DE75512108001245126199
        postalAddress:
          $ref: '#/components/schemas/PostalAddress'
        identification:
          $ref: '#/components/schemas/IdentificationCreditor'
      additionalProperties: false
    Identification:
      type: object
      properties:
        organisationIdentification:
          $ref: '#/components/schemas/OrganisationIdentification'
        privateIdentification:
          $ref: '#/components/schemas/PrivateIdentification'
      additionalProperties: false
    OrganisationIdentification:
      type: object
      description: Allows for the simultaneous inclusion of BIC, LEI and/or Other.
      properties:
        bic:
          minLength: 1
          pattern: '[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}'
          type: string
          description: Business identifier code (BIC) - Code allocated to a financial institution by the ISO 9362 Registration Authority. BIC8 and BIC11 allowed.
          example: BUKBNL20
        lei:
          maxLength: 20
          minLength: 20
          pattern: '[A-Z0-9]{18,18}[0-9]{2,2}'
          type: string
          description: Legal Entity Identifier (LEI) - Unique alphanumeric code that has 20 characters and is based on the ISO 17442 standard.
          example: 724500EAW1MTCM9M1X68
        other:
          type: object
          required:
          - identificationNumber
          properties:
            identificationNumber:
              type: string
              pattern: ^[0-9a-zA-Z-?:().,'+]((?!//)([0-9a-zA-Z-?:().,'+/ ]))+[0-9a-zA-Z-?:().,'+]$
              maxLength: 35
              description: Identification code of the reference party.
              example: '123456789'
            schemeNameCode:
              type: string
              description: 'Scheme Name Code. Only schemeNameCode or schemeNameProprietary can be populated, not both. Allowed values include: BANK, CBID, CHID, CINC, COID, CUST, DUNS, EMPL, GS1G, SREN, SRET, SIRET, TXID, BDID, BOID'
              example: BANK
            schemeNameProprietary:
              type: string
              pattern: ^[0-9a-zA-Z-?:().,'+]((?!//)([0-9a-zA-Z-?:().,'+/ ]))+[0-9a-zA-Z-?:().,'+]$
              maxLength: 35
              description: Scheme Name Proprietary. Only schemeNameCode or schemeNameProprietary can be populated, not both.
              example: SchemeName
            issuer:
              type: string
              pattern: ^[0-9a-zA-Z-?:().,'+]((?!//)([0-9a-zA-Z-?:().,'+/ ]))+[0-9a-zA-Z-?:().,'+]$
              maxLength: 35
              description: The name of the entity that assigns the identification.
              example: IssuerName
      additionalProperties: false
    CreateSepaOutboundPaymentRequest:
      required:
      - amount
      - creditor
      - currency
      - debtor
      - endToEndId
      - remittanceInformationUnstructured
      type: object
      properties:
        endToEndId:
          minLength: 1
          maxLength: 35
          pattern: ([0-9a-zA-Z\-\?:\(\)\.,'\+](/?([0-9a-zA-Z\-\?:\(\)\.,'\+ ]/?)*[0-9a-zA-Z\-\?:\(\)\.,'\+]+)?)
          type: string
          description: Unique identification, as assigned by the originating party, to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.
          example: End2EndId
        amount:
          type: number
          description: Amount of money to be moved between the debtor and creditor, before deduction of charges.
          format: double
          minimum: '0.01'
          maximum: 999,999,999.99
          example: '2.99'
        currency:
          minLength: 1
          pattern: ^[A-Z]{3}$
          type: string
          description: An active or a historic currency where the unit of currency is explicit and compliant with ISO 4217.
          example: EUR
        debtor:
          $ref: '#/components/schemas/Debtor'
        creditor:
          $ref: '#/components/schemas/Creditor'
        creditorAgent:
          $ref: '#/components/schemas/CreditorAgent'
        remittanceInformationUnstructured:
          maxLength: 140
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type: string
          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. Test the return of an SCT payment in the simulation environment by populating with '--SCTRETURN--'
          example: My remittance information.
      additionalProperties: false
    OrganisationIdentificationCreditor:
      type: object
      description: Creditor identification allowing only one of bic, lei, or other.
      oneOf:
      - type: object
        properties:
          bic:
            minLength: 1
            pattern: '[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}'
            type: string
            description: Business identifier code (BIC) - Code allocated to a financial institution by the ISO 9362 Registration Authority. BIC8 and BIC11 allowed.
            example: BUKBNL20
        additionalProperties: false
      - type: object
        properties:
          lei:
            maxLength: 20
            minLength: 20
            pattern: '[A-Z0-9]{18,18}[0-9]{2,2}'
            type: string
            description: Legal Entity Identifier (LEI) - Unique alphanumeric code that has 20 characters and is based on the ISO 17442 standard.
            example: 724500EAW1MTCM9M1X68
        additionalProperties: false
      - type: object
        properties:
          other:
            type: object
            required:
            - identificationNumber
            properties:
              identificationNumber:
                type: string
                pattern: ^[0-9a-zA-Z-?:().,'+]((?!//)([0-9a-zA-Z-?:().,'+/ ]))+[0-9a-zA-Z-?:().,'+]$
                maxLength: 35
                description: Identification code of the reference party.
                example: '123456789'
              schemeNameCode:
                type: string
                description: 'Scheme Name Code. Only schemeNameCode or schemeNameProprietary can be populated, not both. Allowed values include: BANK, CBID, CHID, CINC, COID, CUST, DUNS, EMPL, GS1G, SREN, SRET, SIRET, TXID, BDID, BOID'
                example: BANK
              schemeNameProprietary:
                type: string
                pattern: ^[0-9a-zA-Z-?:().,'+]((?!//)([0-9a-zA-Z-?:().,'+/ ]))+[0-9a-zA-Z-?:().,'+]$
                maxLength: 35
                description: Scheme Name Proprietary. Only schemeNameCode or schemeNameProprietary can be populated, not both.
                example: SchemeName
              issuer:
                type: string
                pattern: ^[0-9a-zA-Z-?:().,'+]((?!//)([0-9a-zA-Z-?:().,'+/ ]))+[0-9a-zA-Z-?:().,'+]$
                maxLength: 35
                description: The name of the entity that assigns the identification.
                example: IssuerName
        additionalProperties: false
    DateAndPlaceOfBirth:
      type: object
      properties:
        dateOfBirth:
          pattern: '[0-9]{4,4}\-[0-9]{2,2}\-[0-9]{2,2}'
          type:
          - string
          - 'null'
          description: Date of birth of a person
          format: date-time
          example: '2004-05-15'
        placeOfBirth:
          maxLength: 35
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type:
          - string
          - 'null'
          description: Place of birth of a person
          example: Birth Town
      additionalProperties: false
    Debtor:
      required:
      - accountIban
      - name
      type: object
      properties:
        name:
          maxLength: 70
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type: string
          description: The name used to identify the legal owner of the account from which to debit funds.
          example: John Doe
        accountIban:
          minLength: 1
          pattern: '[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}'
          type: string
          description: International Bank Account Number associated with the debtor account to which a debit entry will be made as a result of the transaction.
          example: NL73ABNA0529451824
        postalAddress:
          $ref: '#/components/schemas/DebtorPostalAddress'
        identification:
          $ref: '#/components/schemas/Identification'
      additionalProperties: false
    CreditorAgent:
      type: object
      properties:
        bic:
          minLength: 1
          pattern: '[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}'
          type:
          - string
          - 'null'
          description: Business identifier code (BIC) - Code allocated to a financial institution by the ISO 9362 Registration Authority
          example: BUKBNL20
      additionalProperties: false
    RecallOfOutboundPaymentRequest:
      required:
      - paymentId
      - recallCode
      type: object
      properties:
        paymentId:
          pattern: '[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}'
          maxLength: 36
          type: string
          description: Unique identifier of the Outbound SCT payment to be recalled.
          format: uuid
          example: 1bfb7a86-7d9b-45ff-9d5c-34048efc4c8a
        recallCode:
          minLength: 4
          maxLength: 4
          pattern: ^[A-Z0-9]{1,4}$
          type: string
          description: Reason code to recall an Outbound SCT Payment
          example: CUST
        additionalInfo:
          maxLength: 105
          minLength: 1
          pattern: ^[0-9a-zA-Z\-\?:\(\)\.,'\+]((?!//)([0-9a-zA-Z\-\?:\(\)\.,'\+/ ]))+[0-9a-zA-Z\-\?:\(\)\.,'\+]$
          type:
          - string
          - 'null'
          description: Additional Information
          example: Some additional information.
      additionalProperties: false