Faster payments

When sending payments through our API, Faster Payments are initiated via the POST /{vn}/Payments/FPS endpoint, and confirmation of settlement is provided to you via the Transaction Settled webhook. You can send individual or bulk payments.

ClearBank accounts support inbound and outbound Faster Payments. You can send and receive Faster Payments of up to £1,000,000. Faster Payments are not subject to a cut-off time.

Sometimes you will need to return a faster payment, for example when:

the beneficiary name does not match that of the account number,
the account has been closed or transferred,
the beneficiary has deceased.

To return one single immediate payment, use the POST /v3/payments/fps/return endpoint.

Payments originating overseas need to be sent using a separate endpoint: POST /v2/payments/fps/singlepayment.

Each Faster Payment is validated against these rules:

Element	Type	Validation	Description
`name`	string	maxLength: 140 minLength: 1 pattern: `^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&<>;{@\r\n]$`	Also known as Account Holder Name This the creditor's name. If max length exceeds 35 characters, this will be truncated before sending to scheme.
`reference`	string	maxLength: 35 minLength: 0 pattern: `^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&<>;{@\r\n]$`	Also known as the Payment Reference This is the payment reference under remittance information. If the max length exceeds 18 characters, this will be truncated before sending to scheme.

Pattern: Alphanumeric (uppercase and lowercase) and special characters*.
*Special characters: / (forward slash), - (hyphen), ? (question mark), : (colon), ( (left parenthesis), ) (right parenthesis), . (full stop), , (comma), ’ (right single quote), + (plus sign), (blank space), # (hash), = (equals), ! (exclamation mark), ” (right double quote), % (percentage), & (ampersand), * (asterisk), < (less than), > (greater than), ; (semicolon), { (left curly bracket), @ (commercial at), CrLf (carriage return line feed).

This endpoint uses the endToEndIdentification field as a duplicate check to ensure the request is idempotent.

To protect payment recipients from harm and abuse, outbound payments are subject to screening to check for profanities.

The screening checks the Reference string of the RemittanceInformation object. If any term in this string matches a term on the profanity list, it will be removed and the field will be blank when the payment reaches the beneficiary.

References will be removed if they match terms found in (but not limited to) the Pay.UK profanities list that can be found on the Reference Documents page of the Knowledge Centre. This can be accessed by signing in to the ClearBank Portal.

The result of the screening can be found in the SupplementaryData object of the Transaction Settled webhook as follows:

Abusive message screening result	Supplementary Data value
Pass (no match)	`AbusiveMessageScreeningResult:Pass`
Fail (match)	`AbusiveMessageScreeningResult:Fail` `AbusiveMessageScreeningIdentifiers:paymentInstruction.creditTransfer.remittanceInformation.structured.creditorReferenceInformation.reference`

In line with legislation to prevent Authorised Push Payment (APP) scams, payments sent via the Faster Payments scheme may be in scope for APP scam reimbursement, allowing for the recovery of 50% of any consumer reimbursement (up to the claim limit) from the receiving Payment Service Provider (PSP). Further details are available on Pay.UK's website.

Only payments sent via scheme are in scope of APP scam reimbursement, however, when you initiate a payment and we identify that the recipient account is held by a ClearBank client, the payment method is updated to internal transfer by default.

To ensure you have control over the payment method and, by extension, your level of liability for reimbursement claims, the POST /v3/payments/fps endpoint contains a enforceSendToScheme Boolean field.

When set to true: the payment will be processed (and billed for) as a Faster Payment regardless of whether it is eligible to be processed as an internal transfer.
When set to false or not included: there will be no change to the existing behaviour.

Send Faster Payments

post/v3/payments/fps

Initiate a payment using the faster payments scheme. This endpoint is FTR compliant.

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. Each payment instruction is validated against the scheme specific rules as well as the ISO20022 specification. Currently, only payments through GBP are supported. We have listed possible currencies for future proofing of the API. The 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.

Parameters

Authorization string, header, Required
Your API Token, retrieved from the web portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request.

Request Payload (application/json)

paymentInstructions array, Required
Details of the payments to be made.
Minimum length
1
Maximum length
10

request

{
  "paymentInstructions": [
    {
      "debtor": {
        "legalEntityIdentifier": "string",
        "address": "string"
      },
      "paymentInstructionIdentification": "string",
      "debtorAccount": {
        "identification": {
          "iban": "string",
          "other": {
            "issuer": "string",
            "identification": "string",
            "schemeName": {
              "code": "BBAN",
              "proprietary": "string"
            }
          }
        }
      },
      "creditTransfers": [
        {
          "paymentIdentification": {
            "instructionIdentification": "string",
            "endToEndIdentification": "string"
          },
          "amount": {
            "currency": "GBP",
            "instructedAmount": 0
          },
          "creditor": {
            "name": "string",
            "legalEntityIndentifier": "string"
          },
          "creditorAccount": {
            "identification": {
              "iban": "string",
              "other": {
                "issuer": "string",
                "identification": "string",
                "schemeName": {
                  "code": "BBAN",
                  "proprietary": "string"
                }
              }
            }
          },
          "remittanceInformation": {
            "structured": {
              "creditorReferenceInformation": {
                "reference": "string"
              }
            }
          },
          "enforceSendToScheme": true
        }
      ]
    }
  ]
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request
404 Not Found
422 Client Error

Accepted

{
  "transactions": [
    {
      "endToEndIdentification": "string",
      "response": "Accepted"
    }
  ],
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Client Error

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Associated Webhooks

Transaction Settled webhook
Payment Message Assessment Failed webhook
Payment Message Validation Failed webhook
Transaction Rejected webhook

This webhook confirms the transaction has settled. For Bacs payments, this is sent on Day 3 of Bacs processing cycle.

Request body

{
    "Type":"TransactionSettled",
    "Version":6,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`TransactionId`	Unique Identification of the Transaction. Type: `GUID` Max. Length: `36` Special Character: Hyphen `-` Example format of a typical TransactionId:`CE25B426-9430-4A82-8EB8-9311DA2D3E12`
`Status`	Transaction status. Type: `string` `Settled`
`Scheme`	Optional The Scheme type. `Transfer` `FasterPayments` `Bacs` `Chaps`
`EndToEndTransactionId`	For outbound Faster Payments and CHAPS transactions, this is the unique identifier you supplied in the endToEndIdentification field in your API request. For inbound CHAPS payments, this is the prefix "II-" followed by the Instruction Identification, which is unique. For outbound cheque transactions, this is the unique identifier you supplied in the MessageId value in your submit a cheque API request. For internal transfers, this will not be unique, as the value specified in the two webhooks describing the transactions applied to the debtor and creditor accounts will match. Type: `string` Max. length:`35`
`Amount`	Transaction amount. Type: `decimal`
`TimestampSettled`	Date and time the transaction settled. Time Zone: `UTC` Type: `DateTime`
`TimestampCreated`	Date and time the transaction was created. Time Zone: `UTC` Type: `DateTime`
`CurrencyCode`	Optional Code of transaction currency. `GBP`
`DebitCreditCode`	Movement of transaction. Type: `string` Options:`Credit`, `Debit`
`Reference`	(optional) Payment transaction reference. Max. length: `140`
`IsReturn`	Is the Transaction returned from Scheme? `True` `False`
`Account`	Account information object Type: `object` It contains the `IBAN`, `BBAN`, `OwnerName`, `TransactionOwner` and `InstitutionName`. `IBAN`: International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN`: Basic Bank Account number associated with the account. Type: `string` Max. length: `30` Depending on Scheme Type `OwnerName`: name of the beneficiary account holder registered with ClearBank®. Type: `string` Max. length: `128` - Faster Payments = Sender’s Account Name - Chaps = Ordering Customer’s Name `TransactionOwnerName` Type: `string` Max. length: `128` - Beneficiary Account Holder, as specified by the remitter in the payment message. - For outbound payments, as specified by ClearBank® as the remitter name in the payment message. `InstitutionName`: The institution name. Max. length: `128` - Chaps = Ordering Institution
`CounterpartAccount`	The account which is not held at ClearBank. It contains the `IBAN`, `BBAN`, `OwnerName`, `TransactionOwner` and `InstitutionName`. `IBAN`(Optional): International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN`(Optional): Basic Bank Account number associated with the account. Type: `string` Max. length: `30` Depending on Scheme Type `OwnerName`: name of the beneficiary account. Type: `string` Max. length: `128` - Populated with either the same name as `TransactionOwnerName`, or with `“Not Provided”` depending on what is provided in the payment message. - Faster Payments = Beneficiary's Account Name `TransactionOwnerName` Type: `string` Max. length: `128` Populated by Scheme with the name provided in the payment message. - For outbound payments, this is populated as the Beneficiary Name which is provided by you. `InstitutionName`: The institution name. Max. length: `128` - Chaps = Beneficiary Institution
`ActualEndToEndTransactionId`	Unique payment Identifier depending on Scheme Type. Maximum Field Length: `255` Faster Payments = `FPID` Chaps = `Instruction Identification` Cheques = `CreditItemId` FPID is the unique payment identifier generated by Faster Payments. Instruction Identification is the unique payment identifier generated by the remitting bank. ICS Credit Item Identification is the unique payment identifier generated by the cheque scheme.
`DirectDebitMandateId`	(Optional) Unique Identification of a Direct Debit Instruction. Type: `GUID` Max. length: `36`
`TransactionCode`	(Optional) Direct Debit Transaction code: `"01"` - First collection `"17"` - Regular collection `"18"` - Re-presented collection `"19"` - Final collection (Optional) Direct Credit Transaction code: `"99"` - Standard Bank Giro Credit `"86"` - Bank to bank settlement `"Z4"` - Interest payment `"Z5"` - Dividend payment
`ServiceUserNumber`	(Optional) Service User's Unique Identifier registered with Bacs. Max. length: `6`
`BacsTransactionId`	(Optional) Type: `GUID` Max. length: `36`
`BacsTransactionDescription`	(Optional) `CreditTransactionSettled` `DebitContraTransactionSettled` `DebitTransactionSettled` `CreditContraTransactionSettled` `DirectDebitReceivedIndemnityClaimSettled`
`TransactionType`	(Optional) `DirectCredit` `DirectDebit` `DirectDebitIndemnityClaim`
`TransactionSource`	(Optional) Origination of the Transaction : Max. length: `50` Example: `CardProcessor`, `Cheques`
`SupplementaryData`	(Optional) Transaction supplementary data It is an array with the a `Name` and `Value`. `Name`: Field Number/Name for an inbound CHAPS or FPS message. Max. length: `33` `Name` options: `20`, `13C`, `23B`, `23E`, `26T`, `32A`, `33B`, `36`, `50a`, `51A`, `52a`, `53a`, `54a`, `55a`, `56a`, `57a`, `59a`, `70`, `71A`, `71F`, `71G`, `72`, `77B`, `SendingFpsInstitution`, `Currency`, `DateSent`, `PaymentType`, `TransactionReferenceNumber`, `Amount`, `OriginatingCreditInstitution`, `OriginatingCustomerAccountNumber`, `OriginatingCustomerAccountName`, `OriginatingCustomerAccountAddress`, `EndToEndReference`, `BeneficiaryCreditInstitution`, `BeneficiaryCustomerAccountNumber`, `BeneficiaryCustomerAccountName`, `BeneficiaryCustomerAccountAddress`, `ReturnedPaymentFpId`, `PaymentReturnCode`, `PaymentSubTypeCode`, `PurposeTransactionType`, `TypeOfAccountCode`, `NumericReference`, `ReferenceInformation`, `RemittanceInformation`, `RegulatoryReporting`, `OriginalCurrency`, `OriginalAmount`, `ExchangeRate`, `ChargingInformation`, `SubmittingMember`, `ReceivingMember`, `SettlementCycleId`, `FileId`, `ProcessedAsynchronously`, `AgencyAccountWithMember`, `AgencySortCodeWithMember`, `RedirectedBeneficiaryCreditInstitution`, `RedirectedBeneficiaryCustomerAccountNumber`, `AbusiveMessageScreeningResult`, `AbusiveMessageScreeningIdentifiers` `Value` Max. length: `500` There could be more than one Name and Value pair.
`Iso20022XmlDocument`	(Optional) Only appears if `Scheme` is Chaps and the message type received is in ISO 20022 (MX) format. Content of the Document node (payload) of the received payment message, to enable processing of ISO 20022 messages for CHAPS. This value can be very long, so we recommend checking your firewall settings to ensure they will not prevent you from receiving the webhook. See below for examples. Type: `string` Min. Length: `0` Max. Length: `80000`
`Nonce`	Cryptographically secure number generated by ClearBank® for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example transaction settled webhook request body for Transfer scheme type

{
    "Type":"TransactionSettled",
    "Version":6,
    "Payload":{
        "TransactionId":"d9162680-7d35-7994-4e38-fa80716899a2",
        "Status":"Settled",
        "Scheme":"Transfer",
        "EndToEndTransactionId":"05726acd06dc",
        "Amount":88.52,
        "TimestampSettled":"2019-01-01T10:02:00.964Z",
        "TimestampCreated":"2019-01-01T11:12:05.101Z",
        "CurrencyCode":"GBP",
        "DebitCreditCode":"Credit",
        "Reference":"51dcf7ba480e61c5a60bbb6c6b774d17",
        "IsReturn":false,
        "Account":{
            "IBAN":"GB00CUBK11223312345678",
            "BBAN":"CUBK11223312345678",
            "OwnerName":"JOHN DOE",
            "TransactionOwnerName":"JOHN DOE",
            "InstitutionName":"CustomerBank"
        },
        "CounterpartAccount":{
            "IBAN":"GB00CUBK44556687654321",
            "BBAN":"CUBK44556687654321",
            "OwnerName":"JANE DOE",
            "TransactionOwnerName":"JANE DOE",
            "InstitutionName":"CustomerBank"
        },
        "ActualEndToEndTransactionId":"e6e7ab2a97d1",
        "DirectDebitMandateId":"cbf17eb8-9e49-2043-2eca-0dae05e27fe5",
        "TransactionCode":"99",
        "ServiceUserNumber":"030201",
        "BacsTransactionId":"3ec6f5b0-0e6b-a30b-7dc4-cdcc0751d448",
        "BacsTransactionDescription":"CreditContraTransactionSettled",
        "TransactionType":"DirectCredit",
        "TransactionSource":"CardProcessor",
        "SupplementaryData":[
            {
                "Name":"20",
                "Value":"AJF9384DGSB48Sd"
            },
            {
                "Name":"23B",
                "Value":"CRED"
            }
        ],
    "Nonce":949893874
}

Example webhook response

{
    "Nonce": 949893874
}

Example transaction settled webhook request body for CHAPS scheme type, Iso20022XmlDocument field present - populated for an inbound credit CHAPS payment of pacs.008 type

{
    "Type": "TransactionSettled",
    "Version": 6,
    "Payload": {
        "TransactionId": "fbb84b68-fb67-4532-bfd6-2b540e341a21",
        "Status": "Settled",
        "Scheme": "Chaps",
        "EndToEndTransactionId": "EndToEndId8",
        "Amount": 9.09,
        "TimestampSettled": "2023-02-15T15:32:52.773Z",
        "TimestampCreated": "2023-02-15T15:32:52.437Z",
        "CurrencyCode": "GBP",
        "DebitCreditCode": "Credit",
        "Reference": "Reference17",
        "IsReturn": false,
        "Account": {
            "IBAN": "GB57CLRB04040100057354",
            "BBAN": "CLRB04040100057354",
            "OwnerName": "Fictional - Name",
            "TransactionOwnerName": "Some Other Name",
            "InstitutionName": "ClearBank"
        },
        "CounterpartAccount": {
            "IBAN": "GB58CLRB04040009547509",
            "OwnerName": "GB58CLRB04040009547509",
            "TransactionOwnerName": "GB58CLRB04040009547509",
            "InstitutionName": "LOYDGB22XXX"
        },
        "ActualEndToEndTransactionId": "EndToEndId8",
        "SupplementaryData": [
            {
                "Name": "20",
                "Value": "InstrId7"
            },
            {
                "Name": "32A",
                "Value": "1909-11-1\r\n9.09"
            },
            {
                "Name": "33B",
                "Value": ""
            },
            {
                "Name": "50K",
                "Value": "DebtorName16\r\nGB58CLRB04040009547509"
            },
            {
                "Name": "52A",
                "Value": "LOYDGB22XXX"
            },
            {
                "Name": "57A",
                "Value": "CLRBGB20XXX"
            },
            {
                "Name": "59",
                "Value": "GB57CLRB04040100057354"
            },
            {
                "Name": "70",
                "Value": "EndToEndId8\r\nReference17"
            },
            {
                "Name": "71A",
                "Value": "DEBT"
            }
        ],
        "Iso20022XmlDocument": "<Document xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns=\"urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08\"><FIToFICstmrCdtTrf><GrpHdr><CreDtTm>1900-02-03T04:00:30+00:00</CreDtTm><NbOfTxs>1</NbOfTxs></GrpHdr><CdtTrfTxInf><PmtId><InstrId>InstrId7</InstrId><EndToEndId>EndToEndId8</EndToEndId><UETR>c2f6a588-8d1a-44cb-af87-4741bf2812a3</UETR></PmtId><IntrBkSttlmAmt Ccy=\"GBP\">9.09</IntrBkSttlmAmt><IntrBkSttlmDt>1909-11-12</IntrBkSttlmDt><ChrgBr>DEBT</ChrgBr><Dbtr><Nm>DebtorName16</Nm></Dbtr><DbtrAcct><Id><IBAN>GB58CLRB04040009547509</IBAN></Id></DbtrAcct><DbtrAgt><FinInstnId><BICFI>LOYDGB22XXX</BICFI></FinInstnId></DbtrAgt><CdtrAgt><FinInstnId><BICFI>CLRBGB20XXX</BICFI></FinInstnId></CdtrAgt><CdtrAcct><Id><IBAN>GB57CLRB04040100057354</IBAN></Id></CdtrAcct><RmtInf><Ustrd>Reference17</Ustrd></RmtInf></CdtTrfTxInf></FIToFICstmrCdtTrf></Document>"
    },
    "Nonce": 1772448763
}

This webhook confirms the payment assessment has failed.

The table below covers common scenarios that can trigger this event. We cannot provide a complete list as these may change. The scenarios provided are designed to be human-readable, and you should be prepared to accept other values in these fields.

Cause of error (non-exhaustive)	'Reasons' field	Scheme type
Duplicate endtoendId	Duplicate transaction has been detected	Faster Payments
Outbound FPS Payment over the £1,000,000 threshold	Scheme amount limit exceeded. 1000000.01 exceeds the limit of 1000000 for transaction with endtoendid 123456789	Faster payments
Outbound FPS Payment to a sort code which is not registered to the scheme (for example, sending a CHAPS payment to a sort code which is not registered to CHAPS)	UnexecutableCode.InboundSchemeNotAccepted; Inbound scheme not accepted	Faster Payments
Failed modulus check due to: Sort code not following the structure; Invalid account number	Modulus check failed	Faster Payments
Outbound FPS Payment from a suspended CB account; Sending from a CB GBP to a CB MCCY account	UnexecutableCode.OutboundPaymentDisabled; Outbound payments disabled	Faster Payments
Outbound FPS Payment into an unfound beneficiary account	No internal account located for Creditor main account with BBAN in payment instruction	Faster Payments
Outbound FPS Payment to an account which can't receive funds (e.g. a disabled or closed account)	UnexecutableCode.InboundPaymentDisabled; Inbound payments disabled	Faster Payments
Outbound CHAPS Payment from a suspended CB account	Debit transactions disabled	CHAPS
Outbound CHAPS Payment with Invalid Creditor Account Credentials	Creditor account number and sort code combination is invalid	CHAPS
Outbound CHAPS Payment with Invalid Source Account Credentials	Account not found	CHAPS
Outbound CHAPS Payment from an account with insufficient funds	InsufficientFunds; The account has insufficient funds	CHAPS
Outbound CHAPS Payment to an invalid CHAPS account	Unable to find chaps routing bic for iban 'GB38SRLG04001112345678' sort code	CHAPS

Request body

{
    "Type":"PaymentMessageAssesmentFailed",
    "Version":1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`MessageId`	Unique ID to identify the message. Type: `string` Format: `GUID` Max. length: `36`
`PaymentMethodType`	Optional The Scheme type. `Transfer` `FasterPayments` `Bacs`, `Chaps`
`AssesmentFailure`	The object describes the failure reason. Type: `object` It contains the `EndToEndId` and `Reasons` elements. `EndToEndId` : Unique Identifier supplied by you in your API request. Type: `string` Max. length: `35` `Reasons`: Reasons why ClearBank will not accept the payment message. Type: `string` Max. length: `100` Example reasons include `Insufficient Funds` and `Account closed`
`AccountIdentification`	The object contains the account identification. Type: `object` It contains the `Debtor` and `Creditors` elements.
`Debtor`	Required Debtor information object. Type: `object` Contains `IBAN` and `BBAN` elements. `IBAN`: International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN`: Basic Bank Account number associated with the account. Type: `string` Max. length: `30`
`Creditors`	Creditors information object. Type: `object` Contains `Reference`, `Amount`, `CurrencyCode` (optional), `IBAN` and `BBAN` elements. `Reference` Type:`string` Max. length: `140` `Amount`: Transaction amount Type:`int` `CurrencyCode` (optional): Code of transaction currency, `GBP` Required `IBAN`: International Bank Account Number associated with the account. Type: `string` Max. length: `34` Required `BBAN`: Basic Bank Account number associated with the account. Type: `string` Max. length: `30`
`Nonce`	Cryptographically secure number generated by ClearBank for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example Payment Message Assessment Failed webhook request body

{
    "Type":"PaymentMessageAssesmentFailed",
    "Version":1,
    "Payload":{
        "MessageId":"624e0276-1b27-4a80-a06d-51759711bc0e",
        "PaymentMethodType":"FasterPayments",
        "AssesmentFailure":[
            {
                "EndToEndId":"51236da640c9",
                "Reasons":[
                    "Insufficient Funds"
                ]
            }
        ],
        "AccountIdentification":{
            "Debtor":{
                "IBAN":"GB00CUBK22002243218765",
                "BBAN":"CUBK22002243218765"
            },
            "Creditors":[
                {
                    "Reference":"b4e062e244c449f8afc7e2a941562768",
                    "Amount":17.95,
                    "CurrencyCode":"GBP",
                    "IBAN":"GB00CUBK44556687654321",
                    "BBAN":"CUBK44556687654321"
                }
            ]
        }
    },
    "Nonce":1082937278
}

Example webhook response

{
    "Nonce": 1082937278
}

This webhook confirms the payment validation has failed.

Cause of error (non-exhaustive)	'Reasons' field	Scheme type
Incorrect characters in the creditor name field	Creditor name must only contain valid Faster Payments characters	Faster Payments
Incorrect characters in the reference field	Payments-0[0].Reference - must only contain valid Faster Payments characters	Faster Payments
Sending to invalid IBAN length	Payments-0[0].Creditor IBAN - must match regex pattern	Faster Payments

Request body

{
    "Type":"PaymentMessageValidationFailed",
    "Version":1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`MessageId`	Unique ID to identify the message. Type: `string` Format: `GUID` Max. length: `36`
`PaymentMethodType`	Required The Scheme type. `Transfer`, `FasterPayments`, `Bacs`, `Chaps`
`EndToEndId`	Unique Identifier supplied by you in your API request. Type: `string` Max. length:`35`
`Reasons`	Examples of possible reasons for failure: - Creditor name must only contain valid Faster Payments characters - Creditor name contains invalid characters - Creditor reference must only contain valid Faster Payments characters - Creditor reference contains invalid characters Type: `string` Max. length: `100`
`AccountIdentification`	Debtor information object Type: `object` It contains the `IBAN`, `BBAN`, `CUID` (optional), `UPIC` (optional), `AccountName` (optional), `AccountHolderLabel` (optional) and `InstitutionName` (optional). `IBAN`: International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN`: Basic Bank Account number associated with the account. Type: `string` Max. length: `30` `CUID` (optional): The CHIPS UID is assigned by the New York Clearing House `UPIC` (optional): Identifier used by the New York Clearing House `AccountName` (optional): Name of the account. Type: `string` Max. length: `128` `AccountHolderLabel` (optional): The account description. Type: `string` Max. length: `100` `InstitutionName` (optional): The institution name Type: `string` Max. length: `128`
`Creditors`	Creditor(s) information object Type: `object` It contains `Reference`,`Amount`,`CurrencyCode`,`IBAN` (optional - oneOf): you will either receive the IBAN or the BBAN field, `BBAN` (optional - oneOf): you will either receive the IBAN or the BBAN field,`CUID` (optional), `UPIC` (optional), `AccountName` (optional), `AccountHolderLabel` (optional) and `InstitutionName` (optional). `Reference`: Payment reference specified by the debtor. Type: `string` Max. length: `140` `Amount`: Transaction amount Type:`int` `CurrencyCode`: Code of transaction currency `IBAN` (optional - oneOf): International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN` (optional - oneOf): Basic Bank Account number associated with the account. Type: `string` Max. length: `30` `CUID` (optional): The CHIPS UID is assigned by the New York Clearing House `UPIC` (optional): Identifier used by the New York Clearing House `AccountName` (optional): Name of the account. Type: `string` Max. length: `128` `AccountHolderLabel` (optional): The account description. Type: `string` Max. length: `100` `InstitutionName` (optional): The institution name Type: `string` Max. length: `128`
`Nonce`	Cryptographically secure number generated by ClearBank for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example payment message validation failed webhook request body

{
    "Type":"PaymentMessageValidationFailed",
    "Version":1,
    "Payload":{
        "MessageId":"164ac6a0-8e15-4592-b99e-c0a7399f1295",
        "PaymentMethodType":"Transfer",
        "ValidationFailure":[
            {
                "EndToEndId":"72db39cd1693",
                "Reasons":[
                    "Creditor name contains invalid characters"
                ]
            }
        ],
        "AccountIdentification":{
            "Debtor":{
                "IBAN":"GB00CUBK22002243218765",
                "BBAN":"CUBK22002243218765",
                "CUID":null,
                "UPIC":null,
                "AccountName":"JANE DOE",
                "AccountHolderLabel":"JANE DOE",
                "InstitutionName":"CustomerBank"
            },
            "Creditors":[
                {
                    "Reference":"86671a4add96f7a9cc569a6a4a601b38",
                    "Amount":17.95,
                    "CurrencyCode":"GBP",
                    "IBAN":"GB00CUBK44556687654321",
                    "BBAN":"CUBK44556687654321",
                    "CUID":null,
                    "UPIC":null,
                    "AccountName":"Bob Robson",
                    "AccountHolderLabel":"Bob Robson",
                    "InstitutionName":"MyBank"
                }
            ]
        }
    },
    "Nonce":1634549462
}

Example webhook response

{
    "Nonce": 1634549462
}

This webhook confirms the payment has been rejected.

Request body

{
    "Type":"TransactionRejected",
    "Version":2,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`TransactionId`	Unique Identification of the Transaction. Type: `GUID` Max. Length: `36` Special Character: Hyphen `-` Example format of a typical TransactionId:`073dca79-13b8-8bf2-b63b-148957caffe9`
`Status`	Transaction status. Type: `string` `Rejected`
`Scheme`	Optional The Scheme type. `Transfer`, `FasterPayments`, `Chaps`
`EndToEndTransactionId`	Unique Identifier supplied by you in your API request. For inbound transactions, this identifier may not be unique. Type: `string` Max. length:`35`
`Amount`	Transaction amount. Type: `number` Format: `decimal`
`TimestampModified`	Date and time the transaction was rejected. Time Zone: `UTC` Type: `DateTime`
`CurrencyCode`	(optional) Code of transaction currency. :`GBP`
`DebitCreditCode`	Movement of transaction. Type: `string` Options:`Credit`, `Debit`
`Reference`	Payment transaction reference Max. length: `140`
`IsReturn`	Is the transaction returned from scheme? `True` `False`
`CancellationReason`	(Optional) Textual representation of CancellationCode giving reason for rejection
`CancellationCode`	(Optional) Code of Cancellation – a combination of SWIFT and ClearBank codes. `AC03`, `AC04`, `AC06`, `AC07`,`AC09`, `AC12`, `AG01`, `AG02`, `AG03`, `AM09`, `BE08` , `BE09`, `CB_AccountHoldersBankrupt`, `CB_AccountNameInvalid`, `CB_AccountSwitched`, `CB_AuthenticationFailure`,`CB_CancelledByBoEController`, `CB_CancelledByChapsMember`,`CB_CancelledCreditAccountDisabled`, `CB_CancelledDebitAccountDisabled`, `CB_CancelledQueuedCloseOfBusiness`, `CB_DupSttlmntOriginalIsQueued`, `CB_DupSttlmntOriginalWasRejected`, `CB_FailedModulusCheck`, `CB_InitiatingPartyActionRequired`, `CB_InitiatingPartyRequested`, `CB_InstructionCancelled`, `CB_InstructionCancelledByCustomer`, `CB_InstructionHasExpired`, `CB_InvalidProcessorState`, `CB_NewAccountUpdatedWithDDI`, `CB_SenderNotInTertiaryMode`, `COSE`, `CURR`, `CUTO`, `DDAT`, `DMON`, `DU05`, `ICAG`, `IVAG`, `MD01`, `MD07`, `OTHR`, `PY01`, `REFE`, `Other`, `Manual`, `BLBYTH`, `HOPRJ`, `MS03`, `MS02`, `AC05`, `MS01`, `CB_PaymentReferenceMissing`, `CB_PaymentReferenceIncorrect`, `CB_PaymentBeneficiaryNameMissing`, `CB_AccountNameAndNumberMismatch`
`Account`	Account information object Type: `object` It contains the `IBAN` and`BBAN`. `IBAN`: International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN`: Basic Bank Account number associated with the account. Type: `string` Max. length: `30`
`CounterpartAccount`	The account which is not held at ClearBank. Type: `object` It contains the `IBAN` and `BBAN`. `IBAN`: International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN`: Basic Bank Account number associated with the account. Type: `string` Max. length: `30`
`Nonce`	Cryptographically secure number generated by ClearBank for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example transaction rejected webhook request body

{
    "Type":"TransactionRejected",
    "Version":2,
    "Payload":{
        "TransactionId":"073dca79-13b8-8bf2-b63b-148957caffe9",
        "Status":"Rejected",
        "Scheme":"Transfer",
        "EndToEndTransactionId":"ccec481ee502",
        "Amount":97.45,
        "TimestampModified":"2018-08-01T23:01:04.635Z",
        "CurrencyCode":"GBP",
        "DebitCreditCode":"Credit",
        "Reference":"06a87c63c88c84b99294d910e283cae6",
        "IsReturn":false,
        "CancellationReason":"Beneficiary account name does not match beneficiary account number",
        "CancellationCode":"CB_AccountNameInvalid",
        "Account":{
            "IBAN":"GB00CUBK11223312345678",
            "BBAN":"CUBK11223312345678"
        },
        "CounterpartAccount":{
            "IBAN":"GB00CUBK44556687654321",
            "BBAN":"CUBK44556687654321"
        }
    },
    "Nonce":748392098
}

Example webhook response

{
    "Nonce": 748392098
}

This webhook confirms that an inbound transaction has been held.

The UK financial sanctions legislation requires that all funds or economic resources belonging to, owned, held or controlled by a designated person must be frozen and reported to the Office of Financial Sanctions Implementation (OFSI). Therefore, whenever an inbound transaction is held by ClearBank for compliance reasons, we apply the funds to a suspense account and send you an Inbound Held Transaction webhook.

Funds associated with a held transaction remain in a suspense account until a decision is made. In some cases, we may contact your compliance department for more information in order to make an informed decision.

If we release a held transaction, the Transaction Settled webhook is raised.
If we decline a held transaction, funds associated with the held transaction are returned to the remitting bank.

To simulate an Inbound Transaction Held webhook in the sim environment, send a payment using the ClearBank Payment Simulator with the Debtor Name field set to 6a41a29eafcf455493.

Request body

{
    "Type":"InboundHeldTransaction",
    "Version":1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`TimestampCreated`	Optional Date and time the transaction was created. Time Zone: `UTC` Type: `DateTime`
`Scheme`	The Scheme type. (Mandatory) `Transfer` `FasterPayments` `Bacs` `Chaps`
`Account`	Mandatory: Account information object Type: `object` It contains the `IBAN`, `BBAN`, associated wiht the account. `IBAN`: International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN`: Basic Bank Account number associated with the account. Type: `string` Max. length: `30`
`CounterpartAccount`	Mandatory: The account from which the payment is being sent (not held at ClearBank). It contains the `IBAN`, `BBAN`, associated with the counterpart account. `IBAN`(Optional): International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN`(Optional): Basic Bank Account number associated with the account. Type: `string` Max. length: `30`
`TransactionAmount`	Optional Transaction amount. Type: `number` Format: `decimal`
`EndToEndTransactionId`	Optional Unique Identifier supplied by you in your API request. For inbound transactions, this identifier might not be unique. Type: `string` Max. length:`35`
`PaymentReference`	(Optional) Payment Transaction Reference (Optional). Max. length: `140`
`Nonce`	Cryptographically secure number generated by ClearBank for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example inbound transaction held webhook request body

{
  "Type": "InboundHeldTransaction",
  "Version": 1,
  "Payload": {
    "TimestampCreated": "2019-03-01T00:00:00Z", (Type: DateTime)
    "Scheme": "Chaps", [ Transfer, FasterPayments, Chaps]
    "Account": {
      "BBAN": "CUBK11223312345678", (MaxLength:30)
      "IBAN": "GB00CUBK11223312345678" (MaxLength:34)
    },
    "CounterpartAccount": {
      "BBAN": "CUBK44556687654321", (MaxLength:30)
      "IBAN": "GB00CUBK44556687654321" (MaxLength:34)
    },
    "TransactionAmount": 88.52,
    "PaymentReference": "ee9a790ea56c142c6b538916c8bd6bcc", (MaxLength:140)
    "EndToEndTransactionId": "5e30e0b4bfb0" (MaxLength:35)
  },
  "Nonce": 1082937278
}

Example webhook response

{
    "Nonce": 1082937278
}

This webhook confirms that an outbound transaction has been held.

The UK financial sanctions legislation requires that all funds or economic resources belonging to, owned, held or controlled by a designated person must be frozen and reported to the Office of Financial Sanctions Implementation (OFSI). Therefore, whenever an outbound transaction is held by ClearBank for compliance reasons, we hold the transaction in a state of Clearing or Pending and send you an Outbound Held Transaction webhook.

You will not have access to funds associated with a held transaction until a decision is made. In some cases, we may contact your Compliance department for more information, in order to make an informed decision.

If we release a held transaction, the Transaction Settled webhook is raised.
If we decline a held transaction, funds associated with the held transaction are returned to you and the Transaction Rejected webhook with the CancellationCode of HOPRJ is raised.

To simulate an Outbound Transaction Held webhook in the sim environment, send a Faster Payment using the POST /v3/payments/fps endpoint with the Name field of the Creditor object set to 6a41a29eafcf455493.

Request body

{
    "Type":"OutboundHeldTransaction",
    "Version":1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`TimestampCreated`	Optional Date and Time the inbound transaction was held. Time Zone: `UTC` Type: `DateTime`
`Scheme`	Mandatory: The Scheme type. `Transfer` `FasterPayments` `Chaps`
`CounterpartAccount`	Mandatory: The account to which the payment is being sent (not held at ClearBank) Type: `object` It contains the `IBAN`, `BBAN`, associated with the account. `IBAN`: International Bank Account Number associated with the account. Type: `string` Max. length: `34` Min. length: `0` `BBAN`: Basic Bank Account number associated with the account. Type: `string` Max. length: `30`
`Account`	Mandatory: Account information object Type: `object` It contains the `IBAN`, `BBAN`, associated with the account. `IBAN`: International Bank Account Number associated with the account. Type: `string` Max. length: `34` Min. length: `0` `BBAN`: Basic Bank Account number associated with the account. Type: `string` Max. length: `30` Min. length: `0`
`TransactionAmount`	Optional Transaction amount. Type: `number` Format: `decimal`
`PaymentReference`	Optional Payment Transaction Reference. Max. length: `140` Min. length: `0`
`EndToEndTransactionId`	Optional Unique Identifier supplied by you in your API request. Type: `string` Max. length:`35` Min. length: `0`
`Nonce`	Cryptographically secure number generated by ClearBank for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example outbound transaction held webhook request body

{
"Type": "OutboundHeldTransaction",
"Version": 1,
"Payload":
{
  "TimestampCreated": "2019-03-01T00:00:00Z", (Type: DateTime)
  "Scheme": "Chaps", [ Transfer, FasterPayments, Chaps]
  "CounterpartAccount": {
    "BBAN": "CUBK44556687654321", (MaxLength:30)
    "IBAN": "GB00CUBK44556687654321" (MaxLength:34)
},
  "Account": {
    "BBAN": "CUBK11223312345678", (MaxLength:30)
    "IBAN": "GB00CUBK11223312345678" (MaxLength:34)
},
  "TransactionAmount": 88.52,
  "PaymentReference": "a6f3c732a6a0b2a8018a06e10c6ecae2",(MaxLength:140)
  "EndToEndTransactionId": "b0c50dc87f86" (MaxLength:35)
}
  "Nonce": 1089558378
}

Example webhook response

{
    "Nonce": 1089558378
}

Return a Faster Payment

post/v3/payments/fps/return

Return an inbound Faster Payment. This endpoint can be used to return domestic payments and payments originating overseas.

This endpoint is the recommended method for returning faster payments that cannot be completed for any reason.

Parameters

Authorization string, header, Required
Your API token, retrieved from the web portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request.

Request Payload (application/json)

paymentReturnInstruction object, Required
Information about the payment return.

request

{
  "paymentReturnInstruction": {
    "TransactionId": "583420ca-a0e3-4e68-b193-c10a8ceb04cc",
    "ReasonForReturn": "string"
  }
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request
403 Forbidden
404 Not Found
422 Client Error

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Client Error

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Associated Webhooks

Transaction Settled webhook
Payment Message Assessment Failed webhook
Payment Message Validation Failed webhook
Transaction Rejected webhook

Send a Faster Payment Originated Overseas

post/v2/payments/fps/singlepayment

To initiate an outbound payment originated overseas, use this single payment endpoint.

Parameters

Authorization string, header, Required
Your API Token, retrieved from the web portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request.

Request Payload (application/json)

paymentInstruction object, Required
Information about the single payment.

request

{
  "paymentInstruction": {
    "debtor": {
      "legalEntityIdentifier": "string"
    },
    "debtorAccount": {
      "identification": {
        "iban": "string",
        "other": {
          "identification": "string",
          "schemeName": {
            "code": "BBAN",
            "proprietary": "string"
          }
        }
      }
    },
    "ultimateDebtor": {
      "name": "string",
      "address": "string"
    },
    "ultimateDebtorAccount": {
      "identification": {
        "bic": "stringst",
        "accountNumber": "string"
      }
    },
    "creditTransfer": {
      "paymentIdentification": {
        "endToEndIdentification": "string"
      },
      "amount": {
        "originalCurrency": "ALL",
        "originalAmount": 0,
        "exchangeRate": 0,
        "instructedAmount": 0
      },
      "creditor": {
        "name": "string",
        "legalEntityIdentifier": "string",
        "address": "string"
      },
      "creditorAccount": {
        "identification": {
          "iban": "string",
          "other": {
            "identification": "string",
            "schemeName": {
              "code": "BBAN",
              "proprietary": "string"
            }
          }
        }
      },
      "remittanceInformation": {
        "structured": {
          "creditorReferenceInformation": {
            "reference": "string"
          }
        },
        "unstructured": {
          "additionalReferenceInformation": {
            "reference": "string"
          }
        }
      }
    }
  }
}

Code copied

Response (application/json)

202 Success
400 Bad Request
404 Not Found

Success

{
  "transaction": {
    "endToEndIdentification": "string",
    "response": "Accepted"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Associated Webhooks

Transaction Settled webhook
Payment Message Assessment Failed webhook
Payment Message Validation Failed webhook
Transaction Rejected webhook

API

GBP Accounts

GBP Payments

Multi-currency/FX

Embedded Banking

Faster payments

Faster Payments

Validation

Abusive message filtering

APP Scam protection

Send Faster Payments

Parameters

Request Payload (application/json)

request

Response (application/json)

Accepted

Bad Request

Client Error

Associated Webhooks

Return a Faster Payment

Parameters

Request Payload (application/json)

request

Response (application/json)

Bad Request

Client Error

Associated Webhooks

Send a Faster Payment Originated Overseas

Parameters

Request Payload (application/json)

request

Response (application/json)

Success

Bad Request

Associated Webhooks