GBP Cross-Border

Cross-border payments are financial transactions where the payer and the recipient are based in separate countries. Our GBP Cross-Border payment product enables you to send sterling payments to any sterling account, in any permissible overseas jurisdiction. Payments are guaranteed to settle on the same-day, as long as the instruction is received before 5pm UK time on that working day.

There is no limit to the amount that can be sent using this service.

You can send GBP cross-border payments using the POST /payments/cross-border-sterling/v3/payments endpoint.

Settlement details are provided to you via the Transaction Settled webhook.

Things to note:

You can initiate a payment during the sterling availability period, 08:00 to 17:00 (UK time), on business days. Payments sent after this window closes will be rejected with a 400 Bad Request response.
If you use version 2, you do not need to provide the details of the intermediary agent. Instead, we'll use the details of the creditor to identify the correct intermediary agent on your behalf. We recommend using version 2 due to this benefit.
If you use version 1 of the endpoint, you'll need to include a GBP Direct Participant in the intermediary agent field.
You can recognise a Transaction Settled webhook that describes a GBP Cross-Border payment by checking the TransactionSource is set to Cross Border GBP.

The GBP Cross-Border endpoint supports the new ISO20022 payment message formats, specifically pacs.008.

Element	Type	Validation	Description
`name`	string	maxLength: 140 minLength: 1 pattern: [0-9a-zA-Z/\-\?:\.,'\+ !#$%&\*=^_`\{\\|\}~";<>@\[\\\]]+	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: [0-9a-zA-Z/\-\?:\.,'\+ !#$%&\*=^_`\{\\|\}~";<>@\[\\\]]+	Also known as the Payment Reference This is the Payment reference under remittance information.

The character set defined by the pattern for the name and reference fields includes all SWIFT allowed characters. These are alphanumeric (uppercase and lowercase) and the special characters shown in this table:

Special character	Description	Special character	Description
!	Exclamation mark	\|	Pipe
#	Hash	}	Right curly bracket
$	Dollar sign	~	Tilde
%	Percent	"	Double straight quote
&	Ampersand	(	Left parenthesis
'	Single straight quote	)	Right parenthesis
*	Asterisk	,	Comma
+	Plus sign	:	Colon
-	Hyphen	;	Semicolon
/	Forward slash	<	Left angle bracket
=	Equals sign	>	Right angle bracket
?	Question mark	@	At sign
^	Caret	[	Left square bracket
_	Underscore	\	Backslash
`	Backtick	]	Right square bracket
{	Left curly bracket

In line with the Bank of England's ISO 20022 data enhancement requirements, you will be required to provide additional details on the debtor and creditor such as the Legal Entity Identifier (LEI), Purpose Code and Category Purpose Code.

You can find further details about these fields on our Knowledge Centre, or access a list of all the recommended Purpose and Category Purpose Codes and their definitions on the Bank of England website: UK recommended Purpose Code PDF.

The LEI is a 20-character, alpha-numeric code based on the ISO 17442 standard and contains information about an entity’s ownership structure. Providing the LEI is mandatory for pacs.008 where the party being described (debtor or creditor) is a financial institution. Otherwise, it is an optional field but strongly recommended to include when the party is an organisation.

The Purpose Code captures the nature of the payment and should be transported end to end. The Purpose Code is 4 characters used to abbreviate the purpose, for example, IVPT - Invoice Payment.

The Category Purpose Code is used to identify the broader nature of the payment and is used by agents. There are fewer Category Purpose Codes as this is providing a higher level understanding. In total there are 127 Purpose Codes and 28 Category Purpose Codes.

To help make sense of the various codes, they have been broken down into eight categories in the following table. The categories have been created by ClearBank to support our clients in finding the appropriate codes for their use case when making GBP Cross-Border payments.

For your convenience, Purpose Codes and Category Purpose Codes with the same value are shown in bold.

Group	Name	Description	Purpose Codes	Category Purpose Codes
1	Personal finance	These codes can be used if the payment relates to something specific to a person, for example, alimony payment or dental services.	ALMY, BECH, BENE, CHAR, CLPR, DNTS, EDUC, GAMB, LOTT, LTCF, MDCS, SALA, SAVG, SSBE, SUBS, TRFD, VIEW	GP2P, MP2P, SALA, SSBE
2	Finance and accounting	These codes can be used if the payment relates to invoices or managing finances.	ACCT, AREN, BKIP, BKPP, CASH, CSDB, INTC, INTP, IVPT, LIMA, NETT, REOD, TREA, LOAN, LOAR, INTE	CASH, TREA, INTC, INTE, LOAN
3	Corporate	These codes can be used if the payment relates to topics that impact corporations.	ADCS, AGRT, BEXP, BONU, COMC, COMM, COMP, COMT, CPYR, DEPT, DIVD, ECPR, EPAY, GDSV, GIFT, GSCB, HREC, INSM, PEFC, REBT, REFU, RELG, ROYA, TRAD, SUPP, PENS	BONU, DIVI, DVPM, PENS, RRCT, SUPP
4	Tax & government specific	These codes can be used if the payment relates to tax or for government related activities.	ESTX, FAND, GOVT, HSTX, PENO, RDTX, TAXR, TAXS, VATX, WHLD, PTXP	GOVT, TAXS, VATX, WHLD
5	Insurance	These codes can be used if the payment relates to insurance.	HLTI, INPC, INPR, INSC, INSU, INTX, LBRI, LIFI, PPTI	OTHR
6	Property	These codes must be used if the payment is related to property. It is a priority to identify these payments correctly.	HLRP, HLST, PCOM, PDEP, PLDS, PLRF	OTHR
7	Financial products	These codes can be used if the payment relates to a financial product.	BKFE, BNET, BOCE, CBLK, CMDT, COLL, CORT, DERI, EXTD, FNET, FORW, FREX, FUTR, FXNT, HEDG, INVS, OTCD, REPO, SBSC, SECU, SLEB, SWFP, SWPP, SWRS, SWUF, LREB, LREV	CBLK, CORT, HEDG, TRAD, SECU
8	Bills and fees	These codes can be used if the payment being made is related to a bill or fee being applied.	CBTV, CDBL, LICF, SERV, TCSC, UBIL, WTER, PHON, ELEC, GASB, CPKC, FEES, BLDM, DBTC, RENT	CCRD, DCRD, FCOL

The following table details common uses of Purpose Codes and Category Purpose Codes which you can refer to when making payments.

Use case	Purpose Code	Category Purpose Code
Buying a property – payment of a deposit	PDEP – Property Deposit	OTHR – Other Payment
Buying a property – final payment to complete the purchase of a property	PCOM – Property Completion Payment	OTHR – Other Payment
Payments made in relation to salaries	SALA – Salary Payment	SALA – Salary Payment
Moving money for the same company from a ClearBank to a non-ClearBank account	INTC – Intra Company Payment	INTC – Intra Company Payment
Moving money for the same individual(s) from a ClearBank to a non-ClearBank account	INTP – Intra Party Payment	GP2P – Person to Person Payment
Paying a supplier	SUPP – Supplier Payment	SUPP – Supplier Payment
Paying a business expense	BEXP – Business Expenses	OTHR – Other Payment
Paying a generic tax bill	TAXS – Tax Payment	TAXS – Tax Payment
Payment of an insurance premium	INSU – Insurance Premium	OTHR – Other Payment
Paying VAT	VATX – Value Added Tax Payment	VATX – Value Added Tax Payment
Making a payment for a trade	TRAD - Trade	CORT – Trade Settlement Payment
Paying an invoice	IVPT – Invoice Payment	CASH – Cash Management Transfer
Paying fees of some sort	FEES – Payment of Fees	OTHR – Other Payment
Payment of building maintenance	BLDM – Building Maintenance	OTHR – Other Payment
Repayment of a loan	LOAR – Loan Repayment	LOAN - Loan
Funding your account at Bank of England (pacs.009)	LIMA – Liquidity Management	CASH – Cash Management Transfer

Send a GBP cross-border payment

post/payments/cross-border-sterling/v3/payments

This endpoint will send a cross-border customer payment in sterling (pacs.008).

Parameters

Authorization string, header, Required
Your API token retrieved from the ClearBank 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)

instructionIdentification string, Required
Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction.\n\nUsage: The instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction.
Minimum length
1
Maximum length
35
endToEndIdentification string, Required
Unique identification, as assigned by the initiating party, to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain. Usage: The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction. Usage: In case there are technical limitations to pass on multiple references, the end-to-end identification must be passed on throughout the entire end-to-end chain.
Minimum length
1
Maximum length
35
instructedAmount object, Required
A number of monetary units specified in an active or a historic currency where the unit of currency is explicit and compliant with ISO 4217.
sourceAccount object, Required
The ClearBank account that will be credited or debited based on the successful completion of the payment instruction. You need to include EITHER iban OR schemeName, proprietary, and identification as shown in the groups below.
debtorAccount object, Required
Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction. You need to include EITHER iban OR schemeName, proprietary, and identification as shown in the groups below.
debtor object, Required
Party that owes an amount of money to the (ultimate) creditor.
creditorAccount object, Required
Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction. You need to include EITHER iban OR schemeName, and identification as shown in the groups below.
creditor object, Required
Party to which an amount of money is due.
creditorAgent object, Required
purpose string, Required
Underlying reason for the payment transaction, as published in an external Purpose Code list.
Minimum length
4
Maximum length
4
Enum array
BKFE, BKIP, BKPP, CBLK, ACCT, CASH, COLL, CSDB, DEPT, INTC, INTP, LIMA, NETT, EXTD, OTCD, REPO, SBSC, SLEB, AGRT, AREN, BEXP, BOCE, COMC, CPYR, GDSV, GSCB, LICF, ROYA, SERV, SUBS, SUPP, TRAD, CHAR, COMT, ECPR, EPAY, CLPR, COMP, DBTC, HLRP, HLST, INPC, INPR, INSC, INSU, INTE, LBRI, LIFI, LOAN, LOAR, PENO, PPTI, RELG, TRFD, FORW, FXNT, BLDM, BNET, CDBL, CORT, CPKC, EDUC, FAND, FEES, GIFT, GOVT, INSM, IVPT, REBT, REFU, RENT, REOD, TCSC, CMDT, DERI, DIVD, FREX, HEDG, INVS, SAVG, SECU, TREA, FNET, FUTR, DNTS, HLTI, LTCF, MDCS, VIEW, SWFP, SWPP, SWRS, SWUF, ADCS, ALMY, BECH, BENE, BONU, COMM, HREC, PEFC, PENS, SALA, SSBE, LREB, LREV, ESTX, HSTX, INTX, PTXP, RDTX, TAXS, VATX, WHLD, TAXR, CBTV, ELEC, GASB, PHON, UBIL, WTER, GAMB, LOTT, PCOM, PDEP, PLDS, PLRF
categoryPurpose string, Required
Broader nature of the payment, as published in an external Category Purpose Code list.
Minimum length
4
Maximum length
4
Enum array
BONU, CASH, CBLK, CCRD, CORT, DCRD, DIVI, DVPM, FCOL, GP2P, GOVT, HEDG, INTC, INTE, LOAN, MP2P, OTHR, PENS, RRCT, SALA, SECU, SSBE, SUPP, TAXS, TRAD, TREA, VATX, WHLD
remittanceInformation object
Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.
intermediaryAgent1 object

request

{
  "instructionIdentification": "string",
  "endToEndIdentification": "string",
  "instructedAmount": {
    "amount": "1416.98",
    "currency": "GBP"
  },
  "sourceAccount": {
    "iban": "GB12CLBK01020312345678"
  },
  "debtorAccount": {
    "iban": "GB12CLBK01020312345678"
  },
  "debtor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "st",
      "postCode": "string"
    },
    "organisationIdentifier": {
      "bic": "DEUTNL2A",
      "lei": "844517J3KKERBCP9QQ94",
      "otherIdentification": "string"
    },
    "privateIdentifier": {
      "otherIdentification": "string"
    }
  },
  "creditorAccount": {
    "iban": "NL91ABNA04171643008894"
  },
  "creditor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "st",
      "postCode": "string"
    },
    "organisationIdentifier": {
      "bic": "DEUTNL2A",
      "lei": "844517J3KKERBCP9QQ94",
      "otherIdentification": "string"
    },
    "privateIdentifier": {
      "otherIdentification": "string"
    }
  },
  "creditorAgent": {
    "bic": "ABNANL2A"
  },
  "purpose": "SALA",
  "categoryPurpose": "SALA",
  "remittanceInformation": {
    "creditorReferenceInformation": "SALARY25112024"
  },
  "intermediaryAgent1": {
    "name": "ABN AMRO",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "st",
      "postCode": "string"
    },
    "bic": "ABNANL2A",
    "lei": "646700J3LMYRBDP9MA86"
  }
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request

Accepted

{
  "paymentId": "bd382f05e8fa4056b25e"
}

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
Outbound Transaction Held 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 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 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
}

API

GBP Accounts

GBP Payments

Multi-currency/FX

Embedded Banking

GBP Cross-Border

GBP Cross-Border

GBP Cross-Border validation

Version 3 mandatory fields

Legal Entity Identifer (LEI)

Purpose Codes and Category Purpose Codes

Common use case examples

Send a GBP cross-border payment

Parameters

Request Payload (application/json)

request

Response (application/json)

Accepted

Bad Request

Associated Webhooks