CHAPS

ClearBank accounts support inbound and outbound CHAPS payments. As CHAPS is the UK’s high value payment scheme, there is no amount limit associated with inbound or outbound CHAPS payments. However, you can only send or return CHAPS payments between 08:00 – 17:00 Monday to Friday (excluding UK public holidays).

CHAPS payments can be sent using the POST payments/chaps/v4/customer-payments endpoint.
Settlement details are provided to you via the Transaction Settled webhook.
If you need to return a CHAPS payment, you can do so using the POST /payments/chaps/v4/return-payments endpoint.

The latest versions of the CHAPS endpoints support the new ISO20022 payment message formats. See FIN to ISO20022 field mapping for guidance on how the previous MT numbered field values map to the new ISO20022 XML tags.

CHAPS validation

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 CHAPS payment

post/payments/chaps/v5/customer-payments

This endpoint will send a CHAPS customer payment (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. Usage: 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
Pattern
^[0-9a-zA-Z/\-\?:\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$
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
Pattern
^[0-9a-zA-Z/\-\?:\.,'\+ ]+$
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, proprietary, and identification as shown in the groups below.
creditor object, Required
Party to which an amount of money is due.
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.

request

{
  "instructionIdentification": "163f8yk55a9bb4w335qa5f",
  "endToEndIdentification": "5850154964795488434534",
  "instructedAmount": {
    "amount": "1477.85",
    "currency": "GBP"
  },
  "sourceAccount": {
    "iban": "string"
  },
  "debtorAccount": {
    "iban": "string"
  },
  "debtor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "st",
      "postCode": "string"
    },
    "organisationIdentifier": {
      "bic": "string",
      "lei": "646700J3LMYRBDP9MA86",
      "otherIdentification": "string"
    },
    "privateIdentifier": {
      "otherIdentification": "string"
    }
  },
  "creditorAccount": {
    "iban": "string"
  },
  "creditor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "st",
      "postCode": "string"
    },
    "organisationIdentifier": {
      "bic": "string",
      "lei": "646700J3LMYRBDP9MA86",
      "otherIdentification": "string"
    },
    "privateIdentifier": {
      "otherIdentification": "string"
    }
  },
  "purpose": "LOAN",
  "categoryPurpose": "LOAN",
  "remittanceInformation": {
    "creditorReferenceInformation": "ACC88451775LOAN"
  }
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request

Accepted

{
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7"
}

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

Return a CHAPS payment

post/payments/chaps/v5/return-payments

Return a CHAPS payment. All CHAPS returns must be made by the next working day. The same operating hours apply for CHAPS returns as for regular CHAPS payments. Note that this endpoint only supports returning CHAPS payments made after the Bank of England's RTGS Renewal Programme went live (all payments made on or after 19 June 2023).

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)

paymentId string, Required
ClearBank identifier that uniquely identifies the inbound payment instruction.
reason string, Required
Specifies the reason for the return.
Enum array
AC01, AC02, AC03, AC04, AC06, AC07, AC13, AC14, AC15, AC16, AC17, AG01, AG02, AG07, AGNT, AM01, AM02, AM03, AM04, AM05, AM06, AM07, AM09, AM10, ARDT, BE01, BE04, BE05, BE06, BE07, BE08, BE10, BE11, BE16, BE17, CN01, CNOR, CNPC, CURR, CUST, DNOR, DS28, DT01, DT02, ED01, ED03, ED05, EMVL, ERIN, FF03, FF04, FF05, FF06, FF07, FOCR, FR01, FRTR, G004, MD01, MD02, MD05, MD06, MD07, MS02, MS03, NOAS, NOCM, NOOR, PINL, RC01, RC07, RC08, RC11, RF01, RR01, RR02, RR03, RR04, RR05, RR06, RR07, RR08, RR09, RR11, RR12, RUTA, SL01, SL02, SL11, SL12, SL13, SL14, SP01, SP02, SVNR, TM01, TRAC, UPAY
instructionIdentification string, Required
Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction. Usage: 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
Pattern
^[0-9a-zA-Z/\-\?:\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$

request

{
  "paymentId": "bd382f05e8fa4056b25e531e561",
  "reason": "AC04",
  "instructionIdentification": "string"
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request

Accepted

{
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7"
}

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

Send a CHAPS bank-to-bank payment

post/payments/chaps/v5/institution-payments

Create an outbound bank-to-bank payment. This endpoint is used to send CHAPS Pacs.009 payments between financial institutions and is only available to authorised institutions.

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. Usage: 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
Pattern
^[0-9a-zA-Z/\-\?:\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$
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
Pattern
^[0-9a-zA-Z/\-\?:\.,'\+ ]+$
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.
debtor object, Required
Party that owes an amount of money to the (ultimate) creditor.
creditorAccount object, Required
Party is owed an amount of money as the (ultimate) creditor. You need to include EITHER iban OR schemeName, proprietary, and identification as shown in the groups below.
creditor object, Required
Party to which an amount of money is due.
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.

request

{
  "instructionIdentification": "string",
  "endToEndIdentification": "string",
  "instructedAmount": {
    "amount": "18540.78",
    "currency": "GBP"
  },
  "sourceAccount": {
    "iban": "string"
  },
  "debtor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "st",
      "postCode": "string"
    },
    "lei": "string"
  },
  "creditorAccount": {
    "iban": "string"
  },
  "creditor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "st",
      "postCode": "string"
    },
    "lei": "string"
  },
  "purpose": "INTC",
  "categoryPurpose": "INTC",
  "remittanceInformation": {
    "unstructured": "string"
  }
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request

Accepted

{
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7"
}

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

These endpoints can be used to simulate payments. You can also use them for automated testing.

Simulate an inbound CHAPS payment (pacs.008) through the POST /inbound-payment-simulation/chaps/v1/customer-payments endpoint.
Simulate a returned CHAPS payment (pacs.004) through the POST /inbound-payment-simulation/chaps/v1/return-payments endpoint.
Simulate a CHAPS bank-to-bank payment (pacs.009) through the POST /inbound-payment-simulation/chaps/v1/institution-payments endpoint.

The ClearBank Payment Simulator should no longer be used for CHAPS payments.

Simulate an inbound CHAPS payment

post/inbound-payment-simulation/chaps/v1/customer-payments

Define a CHAPS payment to be received by an account in sim.

This endpoint exists to support your testing and development in our simulation environment. It does not apply to production. You can use it to send a simulated inbound CHAPS payment, so that you will have a payment available to return. Note that if this request is not successful because the payment details are incorrect, you will not receive a webhook.

Parameters

Authorization string, header, Required
Your API token retrieved from the portal
DigitalSignature string, header, Required
The hash of the request body signed with 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.
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.
Minimum length
1
Maximum length
35
instructedAmount object, Required
Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.
debtorBic string, Required
Valid BIC for the debtor account.
Minimum length
1
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 the iban field OR the schemeName and identification fields in this object.
debtor object, Required
Party that owes an amount of money to the (ultimate) creditor.
creditorBic string, Required
Valid BIC for the creditor account.
Minimum length
1
creditorAccount object, Required
Unambiguous identification of the account of the creditor to which a credit entry will be made as a result of the transaction. You need to include EITHER the iban field OR the schemeName and identification fields in this object.
creditor object, Required
Party that is owed an amount of money by the (ultimate) debtor.
purpose string
Underlying reason for the payment transaction, as published in an external purpose code list.
Minimum length
1
Maximum length
35
Enum array
Deposit, IntraCompanyPayment, IntraPartyPayment, AgriculturalTransfer, CommercialPayment, PurchaseSaleOfGoodsAndServices, SupplierPayment, CharityPayment, CompensationPayment, PropertyLoanRepayment, PropertyLoanSettlement, PaymentOfInsuranceClaim, LoanRepayment, TradeSettlementPayment, PaymentOfFees, Gift, InvoicePayment, ForeignExchange, Savings, TaxPayment, Utilities, LotteryPayment, PropertyCompletionPayment, PropertyDeposit, PropertyLoanDisbursement, PropertyLoanRefinancing
categoryPurpose string
Category purpose, in a proprietary form.
Minimum length
1
Maximum length
35
Enum array
TradeSettlementPayment, PersonToPersonPayment, GovernmentPayment, IntraCompanyPayment, Loan, OtherPayment, SupplierPayment, TaxPayment, Trade, TreasuryPayment
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.

request

{
  "instructionIdentification": "string",
  "endToEndIdentification": "string",
  "instructedAmount": {
    "amount": 0,
    "currency": "GBP"
  },
  "debtorBic": "string",
  "debtorAccount": {
    "iban": "string",
    "schemeName": "BBan",
    "identification": "string"
  },
  "debtor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "string",
      "postCode": "string"
    }
  },
  "creditorBic": "string",
  "creditorAccount": {
    "iban": "string",
    "schemeName": "BBan",
    "identification": "string"
  },
  "creditor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "string",
      "postCode": "string"
    }
  },
  "purpose": "Deposit",
  "categoryPurpose": "TradeSettlementPayment",
  "remittanceInformation": {
    "creditorReferenceInformation": "string"
  }
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request

Accepted

{
  "uetr": "string"
}

Code copied

Bad Request

{
  "detail": "string",
  "errors": null,
  "instance": "string",
  "status": "string",
  "title": "string",
  "type": "string"
}

Code copied

Associated Webhooks

Transaction Settled webhook

Simulate a returned CHAPS payment

post/inbound-payment-simulation/chaps/v1/return-payments

Define a returned CHAPS payment to be received by an account in sim.

This endpoint exists to support your testing and development in our simulation environment. It does not apply to production. You can use it to send a simulated returned CHAPS payment. Note that if this request is not successful because the payment details are incorrect, you will not receive a webhook.

Parameters

Request Payload (application/json)

originalUetr string, Required
Universally unique identifier to provide the original end-to-end reference of a payment transaction.
Pattern
[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}
returnReasonCode string, Required
Enum array
WrongAmount, InconsistentWithEndCustomer, MissingCreditorAddress, UnrecognisedInitiatingParty, UnknownEndCustomer, FollowingCancellationRequest, RefundRequestByEndCustomer
originalInstructionIdentification string, Required
Unique identification, as assigned by the original instructing party for the original instructed party, to unambiguously identify the original instruction.
Minimum length
1
Maximum length
35
originalEndToEndIdentification string, Required
Unique identification, as assigned by the original initiating party, to unambiguously identify the original transaction.
Minimum length
1
Maximum length
35
originalReference string, Required
Minimum length
1
instructedAmount object, Required
Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party. Usage: This amount has to be transported unchanged through the transaction chain.
debtorName string
Name of the person or business who owns the debtor account.
debtorBic string, Required
Valid BIC for the debtor account.
Minimum length
1
creditorName string
Name of the person or business who owns the creditor account.
creditorBic string, Required
Valid BIC for the creditor account.
Minimum length
1

request

{
  "originalUetr": "string",
  "returnReasonCode": "WrongAmount",
  "originalInstructionIdentification": "string",
  "originalEndToEndIdentification": "string",
  "originalReference": "string",
  "instructedAmount": {
    "amount": 0,
    "currency": "GBP"
  },
  "debtorName": "string",
  "debtorBic": "string",
  "creditorName": "string",
  "creditorBic": "string"
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request

Accepted

{
  "uetr": "string"
}

Code copied

Bad Request

{
  "detail": "string",
  "errors": null,
  "instance": "string",
  "status": "string",
  "title": "string",
  "type": "string"
}

Code copied

Associated Webhooks

Transaction Settled webhook

Simulate a CHAPS bank-to-bank payment

post/inbound-payment-simulation/chaps/v1/institution-payments

Define a CHAPS bank-to-bank payment to be received by an account in sim.

This endpoint exists to support your testing and development in our simulation environment. It does not apply to production. You can use it to send a simulated inbound bank-to-bank payment. Note that if this request is not successful because the payment details are incorrect, you will not receive a webhook.

Parameters

Request Payload (application/json)

instructionIdentification string, Required
Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify 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.
Minimum length
1
Maximum length
35
instructedAmount object, Required
Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.
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 the iban field OR the schemeName and identification fields in this object.
debtorBic string, Required
Valid BIC for the debtor account.
Minimum length
1
debtor object, Required
Party that owes an amount of money to the (ultimate) creditor.
creditorBic string, Required
Valid BIC for the creditor account.
Minimum length
1
creditorAccount object, Required
Unambiguous identification of the account of the creditor to which a credit entry will be made as a result of the transaction. You need to include EITHER the iban field OR the schemeName and identification fields in this object.
creditor object, Required
Party that owes an amount of money to the (ultimate) creditor.
purpose string
Underlying reason for the payment transaction, as published in an external purpose code list.
Minimum length
1
Maximum length
35
Enum array
Deposit, IntraCompanyPayment, IntraPartyPayment, AgriculturalTransfer, CommercialPayment, PurchaseSaleOfGoodsAndServices, SupplierPayment, CharityPayment, CompensationPayment, PropertyLoanRepayment, PropertyLoanSettlement, PaymentOfInsuranceClaim, LoanRepayment, TradeSettlementPayment, PaymentOfFees, Gift, InvoicePayment, ForeignExchange, Savings, TaxPayment, Utilities, LotteryPayment, PropertyCompletionPayment, PropertyDeposit, PropertyLoanDisbursement, PropertyLoanRefinancing
categoryPurpose string
Category purpose, in a proprietary form.
Minimum length
1
Maximum length
35
Enum array
TradeSettlementPayment, PersonToPersonPayment, GovernmentPayment, IntraCompanyPayment, Loan, OtherPayment, SupplierPayment, TaxPayment, Trade, TreasuryPayment
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.

request

{
  "instructionIdentification": "string",
  "endToEndIdentification": "string",
  "instructedAmount": {
    "amount": 0,
    "currency": "GBP"
  },
  "debtorAccount": {
    "iban": "string",
    "schemeName": "BBan",
    "identification": "string"
  },
  "debtorBic": "string",
  "debtor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "string",
      "postCode": "string"
    }
  },
  "creditorBic": "string",
  "creditorAccount": {
    "iban": "string",
    "schemeName": "BBan",
    "identification": "string"
  },
  "creditor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "string",
      "postCode": "string"
    }
  },
  "purpose": "Deposit",
  "categoryPurpose": "TradeSettlementPayment",
  "remittanceInformation": {
    "unstructured": "string"
  }
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request

Accepted

{
  "uetr": "string"
}

Code copied

Bad Request

{
  "detail": "string",
  "errors": null,
  "instance": "string",
  "status": "string",
  "title": "string",
  "type": "string"
}

Code copied

Associated Webhooks

Transaction Settled webhook

As part of the Bank of England's RTGS Renewal Programme, the previous message format known as MT messages has changed to MX messages that are compliant with ISO20022.

This table provides information on the most relevant fields within the messages and their associated conversions.

Field	Field name	MT103	MT202	Explanation	pacs.008 (MT103 successor)	pacs.009 (MT202 successor)	pacs.004 (MT202 RTN successor)
:20	Transaction Reference Number	Mandatory	Mandatory	This field specifies the unique reference assigned by the sender to unambiguously identify the message.	<PmtId><InstrId>	<PmtId><InstrId>	<RtrId>
:21	Related Reference		Mandatory	This field contains a reference to the related transaction.		<PmtId><EndToEndId>	<OrgnlInstrId>
:23B	Bank Operation Code	Mandatory		This field identifies the type of operation. By the nature of the ISO message, the payment is always credit, so there is no need to specify the type in the message itself. In FIN, it's usually populated CRED - Normal credit transfer.
:32A	Value date / Currency / Interbank Settled	Mandatory	Mandatory	This field specifies the value date, currency, and settlement amount. The settlement amount is the amount to be booked/reconciled at interbank level.	<IntrBkSttlmAmt><Ccy> <IntrBkSttlmDt>	<IntrBkSttlmAmt><Ccy> <IntrBkSttlmDt>	<RtrdIntrBkSttlmAmt><Ccy> <IntrBkSttlmDt>
:50A, F, or K	Ordering Customer (Payer)	Mandatory		This field specifies the customer ordering the transaction.	<Dbtr> <DbtrAcct>		<RtrChain><Dbtr><Pty>
:52A or D	Ordering Institution (Payer's Bank)	Optional	Optional	This field specifies the financial institution of the ordering customer.	<DbtrAgt> Supercedes Field 52a - Ordering Institution <DbtrAgtAcct> Supercedes Field 52a - Ordering Institution Account Number subfield	<Dbtr> Supercedes Field 52a - Ordering Institution <DbtrAcct> Supercedes Field 52a - Ordering Institution Account Number subfield	<RtrChain><Dbtr><Agt>
:57A, B, C, or D	Account with Institution (Beneficiary's Bank)	Optional	Optional	This field specifies the financial institution which services the account for the beneficiary customer.	<CdtrAgt> Supercedes Field 57a – Account With Institution <CdtrAgtAcct> Supercedes Field 57a – Account With Institution Account Number subfield	<CdtrAgt> Supercedes Field 57a – Account With Institution <CdtrAgtAcct> Supercedes Field 57a – Account With Institution Account Number subfield	<RtrChain><CdtrAgt>
:58A or D	Beneficiary Institution		Mandatory	This field specifies the financial institution which has been designated by the ordering institution as the ultimate recipient of the funds being transferred.		<Cdtr> <CdtrAcct>	<RtrChain><Cdtr><Agt>
:59 or 59A, F	Beneficiary	Mandatory		This field specifies the customer which will be paid.	<Cdtr> <CdtrAcct>		<RtrChain><Cdtr><Pty>
:70	Remittance Information (payment reference)	Optional		This field specifies either the details of the individual transaction, or a reference to another message containing the details which are to be transmitted to the beneficiary customer.	<PmtId><EndToEndId> Supercedes Field 70 - preceded by codeword /ROC/ <UltmtDbtr> Supercedes Field 70 - preceded by codeword /ULTD/ <UltmtCdtr> Supercedes Field 70 - preceded by codeword /ULTB/ <RltdRmtInf> Supercedes Field 70 - preceded by codeword /RELID/ <RmtInf> Supercedes Field 70 - Remittance Information	<RmtInf>
:71A	Details of Charges	Mandatory		This field specifies which party will bear the charges for the transaction. Previous FIN charge codes: BEN - Beneficiary OUR - Our Customer charged SHA - Shared Charges	<ChrgBr> Borne by Creditor - CRED Borne by Debtor - DEBT Shared - SHAR		<ChrgBr> Borne by Creditor - CRED Borne by Debtor - DEBT Shared - SHAR
:72	Sender to Receiver Information	Optional	Optional	This field specifies additional information for the Receiver or other party specified. Previously, in FIN, if the first six characters in line 1 contain the character string /REJT/ or /RETN/, then it is mandatory to follow the Payments Reject/Return Guidelines described in the Standards MT Usage Guidelines.	<PmtTpInf><LclInstrm> Supercedes Field 72 – preceded by codeword /LOCINS/ <PrvsInstgAgt1><PrvsInstgAgt2><PrvsInstgAgt3> Supercedes Field 72 – preceded by codeword /INS/ <InstgAgt> Sender <InstdAgt>Receiver <IntrmyAgt2><IntrmyAgt3> Supercedes Field 72 – preceded by codeword /INTA/ <InstrForCdtrAgt> Supercedes Field 72 – preceded by codeword /ACC/ <InstrForNxtAgt> Supercedes Field 72 – preceded by codeword /REC/	<PmtTpInf><LclInstrm> Supercedes Field 72 – preceded by codeword /LOCINS/ Also CLS-specific codewords <PmtTpInf><CtgyPurp> Supercedes Field 72 – preceded by codeword /CATPURP/ <PrvsInstgAgt1><PrvsInstgAgt2><PrvsInstgAgt3> Supercedes Field 72 – preceded by codeword /INS/ <IntrmyAgt2><IntrmyAgt3> Supercedes Field 72 – preceded by codeword /INTA/ <DbtrAgt> Supercedes Field 72 – preceded by codeword /INS/ <InstrForCdtrAgt> Supercedes Field 72 – preceded by codeword /ACC/, /PHONBEN/, /TELEBEN/ <InstrForNxtAgt> Supercedes Field 72 – preceded by codeword /REC/ <Purp> Supercedes Field 72 – preceded by codeword /PURP/ <RmtInf> Supercedes Field 72 – preceded by codeword /BNF/ or /TSU/	<RtrRsnInf><Rsn><Cd> Supercedes Field 72 - Sender to Receiver Info - Line 2 <OrgnlEndToEndId> Supercedes Field 72 - Sender to Receiver Info - Line 4 <ChrgsInf><Amt> Supercedes Field 72 - Sender to Receiver Info - Line 5 <OrgnlIntrBkSttlmDt> Supercedes Field 72 - Sender to Receiver Info - Line 6

The following table details the CHAPS return reason codes used to populate the reason field of the Return a CHAPS payment endpoint.

Code Value	Code Name	Code Definition
AC01	IncorrectAccountNumber	Format of the account number specified is not correct.
AC02	InvalidDebtorAccountNumber	Debtor account number invalid or missing.
AC03	InvalidCreditorAccountNumber	Wrong IBAN in SCT.
AC04	ClosedAccountNumber	Account number specified has been closed on the bank of account's books.
AC06	BlockedAccount	Account specified is blocked, prohibiting posting of transactions against it.
AC07	ClosedCreditorAccountNumber	Creditor account number closed.
AC13	InvalidDebtorAccountType	Debtor account type is missing or invalid.
AC14	InvalidAgent	An agent in the payment chain is invalid.
AC15	AccountDetailsChanged	Account details have changed.
AC16	AccountInSequestration	Account is in sequestration.
AC17	AccountInLiquidation	Account is in liquidation.
AG01	TransactionForbidden	Transaction forbidden on this type of account (formerly NoAgreement).
AG02	InvalidBankOperationCode	Bank Operation code specified in the message is not valid for receiver.
AG07	UnsuccesfulDirectDebit	Debtor account cannot be debited for a generic reason. Usage: Code value may be used in general purposes and as a replacement for AM04 if debtor bank does not reveal its customer's insufficient funds for privacy reasons.
AGNT	IncorrectAgent	Agent in the payment workflow is incorrect.
AM01	ZeroAmount	Specified message amount is equal to zero.
AM02	NotAllowedAmount	Specific transaction/message amount is greater than allowed maximum.
AM03	NotAllowedCurrency	Specified message amount is a non-processable currency outside of existing agreement.
AM04	InsufficientFunds	Amount of funds available to cover specified message amount is insufficient.
AM05	Duplication	Duplication
AM06	TooLowAmount	Specified transaction amount is less than agreed minimum.
AM07	BlockedAmount	Amount specified in message has been blocked by regulatory authorities.
AM09	WrongAmount	Amount received is not the amount agreed or expected.
AM10	InvalidControlSum	Sum of instructed amounts does not equal the control sum.
ARDT	AlreadyReturnedTransaction	Already returned original SCT.
BE01	InconsistenWithEndCustomer	Identification of end customer is not consistent with associated account number, organisation ID, or private ID.
BE04	MissingCreditorAddress	Specification of creditor's address, which is required for payment, is missing/not correct (formerly IncorrectCreditorAddress).
BE05	UnrecognisedInitiatingParty	Party who initiated the message is not recognized by the end customer.
BE06	UnknownEndCustomer	End customer specified is not known at associated Sort/National Bank Code or does no longer exist in the books.
BE07	MissingDebtorAddress	Specification of debtor's address, which is required for payment, is missing/not correct.
BE08	BankError	Returned as a result of a bank error.
BE10	InvalidDebtorCountry	Debtor country code is missing or invalid.
BE11	InvalidCreditorCountry	Creditor country code is missing or invalid.
BE16	InvalidDebtorIdentificationCode	Debtor or Ultimate Debtor identification code missing or invalid.
BE17	InvalidCreditorIdentificationCode	Creditor or Ultimate Creditor identification code missing or invalid.
CN01	AuthorisationCancelled	Authorisation is cancelled.
CNOR	CreditorBankIsNotRegistered	Creditor bank is not registered under this BIC in the CSM.
CNPC	CashNotPickedUp	Cash not picked up by Creditor or cash could not be delivered to Creditor.
CURR	IncorrectCurrency	Currency of the payment is incorrect.
CUST	RequestedByCustomer	Cancellation requested by the Debtor.
DNOR	DebtorBankIsNotRegistered	Debtor bank is not registered under this BIC in the CSM.
DS28	ReturnForTechnicalReason	Return following technical problems resulting in erroneous transaction.
DT01	InvalidDate	Invalid date (e.g., wrong settlement date).
DT02	ChequeExpired	Cheque has been issued but not deposited and is considered expired.
ED01	CorrespondentBankNotPossible	Correspondent bank not possible.
ED03	BalanceInfoRequest	Balance of payments complementary info is requested.
ED05	SettlementFailed	Settlement of the transaction has failed.
EMVL	EMVLiabilityShift	The card payment is fraudulent and was not processed with EMV technology for an EMV card.
ERIN	ERIOptionNotSupported	The Extended Remittance Information (ERI) option is not supported.
FF03	InvalidPaymentTypeInformation	Payment Type Information is missing or invalid. Generic usage if cannot specify Service Level or Local Instrument code.
FF04	InvalidServiceLevelCode	Service Level code is missing or invalid.
FF05	InvalidLocalInstrumentCode	Local Instrument code is missing or invalid.
FF06	InvalidCategoryPurposeCode	Category Purpose code is missing or invalid.
FF07	InvalidPurpose	Purpose is missing or invalid.
FOCR	FollowingCancellationRequest	Return following a cancellation request.
FR01	Fraud	Returned as a result of fraud.
FRTR	FinalResponseMandateCancelled	Final response/tracking is recalled as mandate is cancelled.
G004	CreditPendingFunds	In a FIToFI Customer Credit Transfer: Credit to the creditor’s account is pending, status Originator is waiting for funds provided via a cover. Update will follow from the Status Originator.
MD01	NoMandate	No Mandate.
MD02	MissingMandatoryInformationInMandate	Mandate related information data required by the scheme is missing.
MD05	CollectionNotDue	Creditor or creditor's agent should not have collected the direct debit.
MD06	RefundRequestByEndCustomer	Return of funds requested by end customer.
MD07	EndCustomerDeceased	End customer is deceased.
MS02	NotSpecifiedReasonCustomerGenerated	Reason has not been specified by end customer.
MS03	NotSpecifiedReasonAgentGenerated	Reason has not been specified by agent.
NARR	Narrative	Reason is provided as narrative information in the additional reason information. This reason code is not available when sending return payments but may be used by other parties when you receive inbound return payments.
NOAS	NoAnswerFromCustomer	No response from crediting customer.
NOCM	NotCompliant	Customer account is not compliant with regulatory requirements, for example FICA (in South Africa) or any other regulatory requirements which render an account inactive for certain processing.
NOOR	NoOriginalTransactionReceived	Original SCT never received.
PINL	PINLiabilityShift	The card payment is fraudulent (lost and stolen fraud) and was processed as EMV transaction without PIN verification.
RC01	BankIdentifierIncorrect	Bank Identifier code specified in the message has an incorrect format (formerly IncorrectFormatForRoutingCode).
RC07	InvalidCreditorBICIdentifier	Incorrect BIC of the creditor Bank in the SCTR.
RC08	InvalidClearingSystemMemberIdentifier	ClearingSystemMemberidentifier is invalid or missing. Generic usage if cannot specify between debit or credit account.
RC11	InvalidIntermediaryAgent	Intermediary Agent is invalid or missing.
RF01	NotUniqueTransactionReference	Transaction reference is not unique within the message.
RR01	MissingDebtorAccountOrIdentification	Specification of the debtor’s account or unique identification needed for reasons of regulatory requirements is insufficient or missing.
RR02	MissingDebtorNameOrAddress	Specification of the debtor’s name and/or address needed for regulatory requirements is insufficient or missing.
RR03	MissingCreditorNameOrAddress	Specification of the creditor’s name and/or address needed for regulatory requirements is insufficient or missing.
RR04	RegulatoryReason	Regulatory Reason.
RR05	RegulatoryInformationInvalid	Regulatory or Central Bank Reporting information missing, incomplete, or invalid.
RR06	TaxInformationInvalid	Tax information missing, incomplete, or invalid.
RR07	RemittanceInformationInvalid	Remittance information structure does not comply with rules for payment type.
RR08	RemittanceInformationTruncated	Remittance information truncated to comply with rules for payment type.
RR09	InvalidStructuredCreditorReference	Structured creditor reference invalid or missing.
RR11	InvalidDebtorAgentServiceIdentification	Invalid or missing identification of a bank proprietary service.
RR12	InvalidPartyIdentification	Invalid or missing identification required within a particular country or payment type.
RUTA	ReturnUponUnableToApply	Return following investigation request and no remediation possible.
SL01	SpecificServiceOfferedByDebtorAgent	Due to specific service offered by the Debtor Agent.
SL02	SpecificServiceOfferedByCreditorAgent	Due to specific service offered by the Creditor Agent.
SL11	CreditorNotOnWhitelistOfDebtor	Whitelisting service offered by the Debtor Agent; Debtor has not included the Creditor on its “Whitelist” (yet). In the Whitelist, the Debtor may list all allowed Creditors to debit Debtor bank account.
SL12	CreditorOnBlacklistOfDebtor	Blacklisting service offered by the Debtor Agent; Debtor included the Creditor on his “Blacklist”. In the Blacklist, the Debtor may list all Creditors not allowed to debit Debtor bank account.
SL13	MaximumNumberOfDirectDebitTransactionsExceeded	Due to Maximum allowed Direct Debit Transactions per period service offered by the Debtor Agent.
SL14	MaximumDirectDebitTransactionAmountExceeded	Due to Maximum allowed Direct Debit Transaction amount service offered by the Debtor Agent.
SP01	PaymentStopped	Payment is stopped by the account holder.
SP02	PreviouslyStopped	Previously stopped by means of a stop payment advise.
SVNR	ServiceNotRendered	The card payment is returned since a cash amount rendered was not correct or goods or a service was not rendered to the customer, e.g., in an e-commerce situation.
TM01	CutOffTime	Associated message was received after the agreed processing cut-off time.
TRAC	RemovedFromTracking	Return following a direct debit being removed from the tracking process.
UPAY	UnduePayment	Payment is not justified.

CHAPS

CHAPS

Version 5 mandatory fields

Legal Entity Identifer (LEI)

Purpose Codes and Category Purpose Codes

Common use case examples

Send a CHAPS payment

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Return a CHAPS payment

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Send a CHAPS bank-to-bank payment

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

CHAPS simulation endpoints

Simulate an inbound CHAPS payment

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Simulate a returned CHAPS payment

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Simulate a CHAPS bank-to-bank payment

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

FIN to ISO20022 field mapping

CHAPS return reason codes