openapi: 3.2.0 info: title: ClearBank CHAPS RTGS FI API V6 External Customer Payments V6 API version: 6.0-CHAPS tags: - name: ExternalCustomerPaymentsV6 paths: /payments/chaps/v6/customer-payments: post: tags: - ExternalCustomerPaymentsV6 description: Create an outbound customer payment. This endpoint is used to send CHAPS Pacs.008 payments on behalf of customers. operationId: ExternalCreateCustomerPayment-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/CreateCustomerPaymentDtoV6' example: instructionIdentification: INSTR-CUST-001 endToEndIdentification: E2E-CUST-001 interBankSettlementAmount: amount: 1000 currency: GBP sourceAccount: iban: GB29NWBK60161331926819 debtorAccount: schemeName: SortcodeAccountNumber identification: 040004-12345678 debtor: name: Jane Smith creditorAccount: schemeName: SortcodeAccountNumber identification: 200000-55779911 creditor: name: Bob Jones postalAddress: townName: London country: GB postCode: EC2V 8RT purpose: SALA categoryPurpose: SALA remittanceInformation: creditorReferenceInformation: INV-2026-001 application/json-patch+json: schema: $ref: '#/components/schemas/CreateCustomerPaymentDtoV6' text/json: schema: $ref: '#/components/schemas/CreateCustomerPaymentDtoV6' application/*+json: schema: $ref: '#/components/schemas/CreateCustomerPaymentDtoV6' 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 CreateCustomerPaymentDtoV6: required: - instructionIdentification - endToEndIdentification - interBankSettlementAmount - sourceAccount - debtorAccount - 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 description: The ClearBank account that will be credited or debited based on the successful completion of the payment instruction. oneOf: - $ref: '#/components/schemas/AccountIdentificationIbanDtoV6' - $ref: '#/components/schemas/AccountIdentificationOtherDtoV6' debtorAccount: description: Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction. type: object oneOf: - $ref: '#/components/schemas/AccountIdentificationIbanDtoV6' - $ref: '#/components/schemas/AccountIdentificationOtherDtoV6' debtor: $ref: '#/components/schemas/CustomerPartyDetailsDtoV6' description: Party that owes an amount of money to the (ultimate) creditor. type: object creditorAccount: description: Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction. type: object oneOf: - $ref: '#/components/schemas/AccountIdentificationIbanDtoV6' - $ref: '#/components/schemas/AccountIdentificationOtherDtoV6' creditor: $ref: '#/components/schemas/CustomerPartyDetailsDtoV6' description: Party that is owed an amount of money as the (ultimate) creditor. Postal address is required. type: object purpose: $ref: '#/components/schemas/PurposeCodeV6' description: Underlying reason for the payment transaction, as published in an external Purpose Code list. example: LOAN 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: LOAN minLength: 4 maxLength: 4 remittanceInformation: $ref: '#/components/schemas/StructuredRemittanceInformationDtoV6' type: object 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 PrivateIdentifierV6: type: object properties: otherIdentification: description: Other identification of the private individual, such as national insurance number. type: string maxLength: 35 example: AB123456C pattern: ^[0-9a-zA-Z/\-\?:\(\)\.,'\+ ]+$ additionalProperties: false description: Option to provide either OrganisationIdentifier or PrivateIdentifier, but not both. StructuredRemittanceInformationDtoV6: 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: creditorReferenceInformation: description: Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction. type: string minLength: 1 maxLength: 35 pattern: ^[0-9a-zA-Z/\-\?:\(\)\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$ example: INV-2026-001 additionalProperties: false 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 CustomerPartyDetailsDtoV6: required: - name - postalAddress type: object properties: name: description: Name of the person or business who owns the account. type: string minLength: 1 example: Jane Smith pattern: ^[0-9a-zA-Z/\-\?:\(\)\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$ maxLength: 140 postalAddress: $ref: '#/components/schemas/PartyAddressDetailsDtoV6' type: object description: Information that locates and identifies a specific address, as defined by postal services. Required for the creditor. organisationIdentifier: $ref: '#/components/schemas/OrganisationIdentifierV6' type: object privateIdentifier: $ref: '#/components/schemas/PrivateIdentifierV6' type: object 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 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 OrganisationIdentifierV6: type: object properties: bic: description: Bank Identifier Code (BIC) of the entity. BIC11 recommended but BIC8 also supported. type: string pattern: ^[A-Z0-9]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ example: BARCGB22XXX lei: description: Legal Entity Identifier of the entity type: string minLength: 20 maxLength: 20 pattern: ^[A-Z0-9]{18,18}[0-9]{2,2}$ example: 5493001KJH8B2Q3L5X79 otherIdentification: description: For corporate and business customers, we recommend setting this to their 8-character Company Registration Number (CRN) as shown on the Companies House register. Other identifiers such as FCA Firm Reference Numbers (FRNs) are also accepted. type: string maxLength: 35 example: '12345678' pattern: ^[0-9a-zA-Z/\-\?:\(\)\.,'\+ ]+$ additionalProperties: false description: Option to provide either OrganisationIdentifier or PrivateIdentifier, but not both. 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'