ClearBank Faster Payments API
Initiate and manage UK Faster Payments (FPS) and internal transfers, including payment origination overview, for onboarded institutions.
OpenAPI Specification
{
"openapi": "3.0.1",
"info": {
"title": "FI Initiation API 3.0",
"description": "FI Initiation API",
"version": "3.0.FPS-payment"
},
"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.\r\n \r\nEach payment instruction is validated against the scheme specific rules as well as the ISO20022 specification.\r\n \r\nCurrently, only payments through GBP are supported. We have listed possible currencies for future proofing of the API.\r\n \r\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": {
"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",
"example": "GBP",
"description": "Set to 'GBP' as other currencies are not supported.",
"nullable": true
},
"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.00
}
},
"additionalProperties": false,
"description": "Indicates the amount and the currency used in a given transaction or account balance."
},
"BatchCounterpartAccountGenericIdentification": {
"required": [
"identification",
"schemeName"
],
"type": "object",
"properties": {
"issuer": {
"maxLength": 35,
"minLength": 0,
"type": "string",
"description": "The name of the entity that assigns the identification.",
"nullable": true,
"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."
},
"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."
},
"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."
},
"BatchCreditTransferResponse": {
"type": "object",
"properties": {
"transactions": {
"type": "array",
"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.",
"nullable": true
},
"halLinks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HalLink"
},
"description": "Hypermedia links.",
"nullable": true
}
},
"additionalProperties": false,
"description": "The result of each payment instruction and applicable links"
},
"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",
"description": "The legal entity identifier of the account holder (eg: charity number). This should be supplied if known.",
"nullable": true,
"example": "9485839XYZ"
}
},
"additionalProperties": false,
"description": "The name and, optionally, the legal entity identifier of the account."
},
"BatchAdditionalReferenceInformation": {
"type": "object",
"properties": {
"reference": {
"maxLength": 140,
"minLength": 0,
"type": "string",
"description": "Additional remittance information.",
"nullable": true,
"example": "Plumbing payment"
}
},
"additionalProperties": false,
"description": "Reference information provided by the ultimate debtor to allow the identification of underlying documents by the creditor."
},
"BatchCreditorReferenceInformation": {
"type": "object",
"properties": {
"reference": {
"maxLength": 35,
"minLength": 0,
"type": "string",
"description": "A reference, as assigned by the debtor to unambiguously refer to the payment transaction. Conditionally required if supplied by the debtor.",
"nullable": true,
"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."
},
"BatchDebtorPartyIdentifier": {
"required": [
"address"
],
"type": "object",
"properties": {
"legalEntityIdentifier": {
"maxLength": 35,
"minLength": 0,
"type": "string",
"description": "The legal entity identifier of the account holder (eg: charity number). This should be supplied if known.",
"nullable": true,
"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.\r\nMandatory the Address of the account."
},
"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."
},
"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."
},
"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."
},
"BatchPaymentInstructionCounterpartAccountIdentification": {
"type": "object",
"properties": {
"iban": {
"type": "string",
"description": "The International Bank Account Number of the account.",
"nullable": true,
"example": "GB29NWBK60161331926819"
},
"other": {
"$ref": "#/components/schemas/BatchCounterpartAccountGenericIdentification",
"description": "Unique identification of an account, as assigned by the account servicer, using an identification scheme.",
"nullable": true
}
},
"additionalProperties": false,
"description": "The identifiable information of an account."
},
"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).",
"nullable": true
},
"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.",
"nullable": true
}
},
"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."
},
"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.",
"nullable": true
}
},
"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)."
},
"BatchUnstructured": {
"type": "object",
"properties": {
"additionalReferenceInformation": {
"$ref": "#/components/schemas/BatchAdditionalReferenceInformation",
"description": "Additional unstructured remittance information.",
"nullable": true
}
},
"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)."
},
"CounterpartAccountGenericIdentificationScheme": {
"type": "object",
"properties": {
"code": {
"enum": [
"BBAN",
"CUID",
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clearbank/refs/heads/main/openapi/clearbank-fps-initiate-payment-v3.json