ClearBank Multi-Currency Payments API
Orchestrate outbound and inbound multi-currency payments across supported currencies and payment rails for embedded and agency banking customers.
OpenAPI Specification
{
"openapi": "3.0.1",
"info": {
"title": "Mccy Payment Orchestrator External Api V1",
"description": "Mccy Payment Orchestrator External Api V1",
"version": "1.0.Dec21"
},
"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": {
"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",
"minLength": 0,
"maxLength": 35,
"description": "Third line of the creditor's address.",
"nullable": true,
"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",
"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}",
"nullable": true,
"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",
"description": "Creditor's non-SWIFT BIC organisation identification, as assigned by an identification scheme.",
"minLength": 0,
"maxLength": 35,
"nullable": true
},
"schemeName": {
"type": "object",
"description": "Information about the organisation identification scheme in coded form or free-form text.",
"properties": {
"code": {
"type": "string",
"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,
"nullable": true,
"example": "BDID"
},
"proprietary": {
"type": "string",
"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,
"nullable": true,
"example": "Other identification scheme name"
}
}
},
"issuer": {
"type": "string",
"description": "Entity/authority/body responsible for issuing the identification.",
"minLength": 0,
"maxLength": 35,
"nullable": true,
"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",
"description": "Creditor's date of birth.",
"format": "date",
"nullable": true,
"example": "1995-12-27"
},
"cityOfBirth": {
"type": "string",
"description": "Creditor's city of birth.",
"minLength": 0,
"maxLength": 35,
"nullable": true,
"example": "Lisbon"
},
"countryOfBirth": {
"type": "string",
"description": "Two-letter ISO country code for the creditor's country of birth.",
"minLength": 0,
"maxLength": 2,
"pattern": "^[A-Z]{2}$",
"nullable": true,
"example": "PT"
}
}
},
"other": {
"type": "object",
"description": "Information about the creditor's private identification.",
"properties": {
"identification": {
"type": "string",
"description": "Creditor's personal identification, as assigned by an identification scheme. For example, their passport number.",
"minLength": 0,
"maxLength": 35,
"nullable": true,
"example": "020696623"
},
"schemeName": {
"type": "object",
"description": "Information about the identification scheme in coded form, or free-form text.",
"properties": {
"code": {
"type": "string",
"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,
"nullable": true,
"example": "CCPT"
},
"proprietary": {
"type": "string",
"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,
"nullable": true,
"example": "Other identification scheme name"
}
}
}
}
}
}
}
}
},
"countryOfResidence": {
"type": "string",
"description": "Two-letter ISO country code for the creditor's country of residence.",
"minLength": 0,
"maxLength": 2,
"pattern": "^[A-Z]{2}$",
"nullable": true,
"example": "PT"
},
"contactDetails": {
"type": "object",
"description": "Creditor's contact details.",
"properties": {
"name": {
"type": "string",
"description": "Creditor's contact name.",
"minLength": 0,
"maxLength": 140,
"nullable": true,
"example": "Ryan Christensen"
},
"emailAddress": {
"type": "string",
"description": "Creditor's email address.",
"minLength": 0,
"maxLength": 2048,
"nullable": true,
"example": "tokchri@business.eu"
}
}
},
"iban": {
"type": "string",
"description": "Creditor's International Bank Account Number. Mandatory only if account number is not specified.",
"nullable": true,
"example": "ES9242020418450222051122"
},
"accountNumber": {
"type": "string",
"description": "Creditor's Account Number. Mandatory only if iban is not specified.",
"nullable": true,
"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",
"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,
"nullable": true,
"example": "TRAS"
},
"proprietary": {
"type": "string",
"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,
"nullable": true,
"example": "Example other identification scheme"
}
}
}
},
"additionalProperties": false
},
"AccountIdentifierKind": {
"enum": [
"AccountId",
"IBAN"
],
"type": "string",
"description": "The kind of account identifier provided. This can either be IBAN or AccountId. This field is case insensitive."
},
"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
},
"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",
"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}",
"nullable": true,
"example": "NWBKGB2LXXX"
},
"aba": {
"type": "string",
"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,
"nullable": true,
"example": "376582168"
},
"name": {
"type": "string",
"description": "Intermediary agent's name.",
"minLength": 0,
"maxLength": 140,
"nullable": true,
"example": "Intermediary Agent Financial Institution"
},
"addressDetails": {
"type": "object",
"description": "Information about the intermediary agent's address. Mandatory only when financial institution identification details are being provided.",
"nullable": true,
"required": [
"country"
],
"properties": {
"addressLine1": {
"type": "string",
"minLength": 0,
"maxLength": 70,
"description": "First line of the intermediary agent's address.",
"nullable": true,
"example": "12 Banking Building"
},
"addressLine2": {
"type": "string",
"minLength": 0,
"maxLength": 35,
"description": "Second line of the intermediary agent's address.",
"nullable": true,
"example": "Bank Street"
},
"addressLine3": {
"type": "string",
"minLength": 0,
"maxLength": 35,
"description": "Third line of the intermediary agent's address.",
"nullable": true,
"example": "Belfast"
},
"postCode": {
"type": "string",
"minLength": 0,
"maxLength": 16,
"description": "Intermediary agent's postcode.",
"nullable": true,
"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.",
"pattern": "^[A-Z]{2}$",
"example": "GB"
}
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"CreditorAgent": {
"type": "object",
"required": [
"FinancialInstitutionIdentification"
],
"properties": {
"FinancialInstitutionIdentification": {
"type": "object",
"description": "Information that identifies the creditor agent as a financial institution.",
"required": [
"name",
"addressDetails"
],
"properties": {
"bic": {
"type": "string",
"description": "Creditor agent's Business Identifier Code (BIC). No need to specify if you are providing the creditor agent's American Bankers Association (ABA) routing number or Clearing System Id Code.",
"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}",
"nullable": true,
"example": "CBUKGBA132S"
},
"aba": {
"type": "string",
"description": "Creditor agent's American Bankers Association (ABA) routing number. No need to specify if you are providing the creditor agent's Business Identifier Code (BIC) or Clearing System Id Code.",
"minLength": 0,
"maxLength": 35,
"nullable": true,
"example": "853688941"
},
"clearingSystemIdCode": {
"description": "Creditor agent's Clearing System Id Code. No need to specify if you are providing the creditor agent's Business Identifier Code (BIC) or American Bankers Association (ABA) routing number.",
"type": "string",
"minLength": 0,
"maxLength": 35,
"nullable": true,
"example": "GBDSC"
},
"memberId": {
"description": "Creditor agent's Member Id for the specified clearing system. Mandatory only when Clearing System Id Code has been provided.",
"type": "string",
"nullable": true,
"minLength": 0,
"maxLength": 35,
"example": "30-12-77"
},
"name": {
"type": "string",
"description": "Creditor agent's name.",
"minLength": 1,
"maxLength": 140,
"example": "Big FI Cor
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clearbank/refs/heads/main/openapi/clearbank-mccy-payments-v1.json