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`

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"
              }
            }
          }
        }
      ]
    }
  ]
}

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 transactions that are 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: `int`
`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` FPID is the unique payment identifier generated by Faster Payments. Instruction Identification is the unique payment identifier generated by the remitting bank.
`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`
`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.

Scenarios which can trigger this event include (but not limited to); sending a payment which exceeds the scheme limit, sending the payment to a disabled account, sending the payment with a duplicate Payment Id, invalid BIC, CHAPS payment approved outside of the payment window and insufficient balance to cover multiple payments.

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":"Transfer",
        "AssesmentFailure":[
            {
                "EndToEndId":"51236da640c9",
                "Reasons":[
                    "Insufficient Funds"
                ]
            },
            {
                "EndToEndId":"fa2b005bf7a4",
                "Reasons":[
                    "Account closed"
                ]
            }
        ],
        "AccountIdentification":{
            "Debtor":{
                "IBAN":"GB00CUBK22002243218765",
                "BBAN":"CUBK22002243218765"
            },
            "Creditors":[
                {
                    "Reference":"b4e062e244c449f8afc7e2a941562768",
                    "Amount":17.95,
                    "CurrencyCode":"GBP",
                    "IBAN":"GB00CUBK44556687654321",
                    "BBAN":"CUBK44556687654321"
                },
                {
                    "Reference":"0bae808d96bb42a6a892bc9ade169993",
                    "Amount":17.95,
                    "CurrencyCode":"GBP",
                    "IBAN":"GB00CUBK11223312345678",
                    "BBAN":"CUBK11223312345678"
                }
            ]
        }
    },
    "Nonce":1082937278
}

Example webhook response

{
    "Nonce": 828803944
}

This webhook confirms the payment validation has failed.

Scenarios which can trigger this event include (but not limited to); sending a payment with an invalid character in the payment reference and sending a payment with an invalid character in the creditor information.

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`, `BBAN`,`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`: 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`
`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`, `Bacs`, `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.

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). To simulate an inbound held transaction webhook in the simulation environment, enter 6a41a29eafcf455493 in the PaymentReference field. 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.

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. To simulate an outbound held transaction webhook in the simulation environment, enter 6a41a29eafcf455493 in the PaymentReference field. 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

UK Payments

Multi-currency/FX

Embedded Banking

Faster payments

Faster Payments

Validation

Abusive message filtering

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