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

Send a CHAPS payment

postpayments/chaps/v4/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 you, to unambiguously identify the payment 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.
Minimum length
1
Maximum length
35
Pattern
^[0-9a-zA-Z/\-\?:\.,'\+ ]+$
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.
sourceAccount object, Required
The ClearBank account that will be debited based on the successful completion of the payment instruction. You need to include EITHER the iban field OR the schemeName and identification fields in this object.
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
creditorAccount object, Required
Party is owed an amount of money as the (ultimate) creditor. You need to include EITHER the iban field OR the schemeName and identification fields in this object.
creditor object, Required
purpose string
Underlying reason for the payment transaction, as published in an external purpose code list.
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.
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"
  },
  "sourceAccount": {
    "iban": "string",
    "schemeName": "Other",
    "proprietary": "SortcodeAccountNumber",
    "identification": "01020301234567"
  },
  "debtorAccount": {
    "iban": "string",
    "schemeName": "Other",
    "proprietary": "SortcodeAccountNumber",
    "identification": "01020301234567"
  },
  "debtor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "string",
      "postCode": "string"
    },
    "lei": "string"
  },
  "creditorAccount": {
    "iban": "string",
    "schemeName": "Other",
    "proprietary": "SortcodeAccountNumber",
    "identification": "01020301234567"
  },
  "creditor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "string",
      "postCode": "string"
    },
    "lei": "string"
  },
  "purpose": "Deposit",
  "categoryPurpose": "TradeSettlementPayment",
  "remittanceInformation": {
    "creditorReferenceInformation": "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

Return a CHAPS payment

post/payments/chaps/v4/return-payments

Use this endpoint to return a CHAPS payment.

If you need to return a payment, you should do so 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, that is, to all payments made on or after 19 June 2023.

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)

paymentId string, Required
Payment ID assigned by ClearBank to the inbound payment. This is the same value as the TransactionId in the Transaction Settled webhook.
reason string, Required
Specifies the reason for the return.
Enum array
WrongAmount, InconsistentWithEndCustomer, MissingCreditorAddress, UnrecognisedInitiatingParty, UnknownEndCustomer, FollowingCancellationRequest, RefundRequestByEndCustomer
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
Pattern
^[0-9a-zA-Z/\-\?:\.,'\+ !#$%&\*=^_`\{\|\}~";<>@\[\\\]]+$

request

{
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "reason": "WrongAmount",
  "instructionIdentification": "string"
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request

Accepted

{
  "paymentId": "9e987f04-4c84-1009-ef88-a9121bc8948f"
}

Code copied

Bad Request

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

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/v4/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

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
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.
Minimum length
1
Maximum length
35
Pattern
^[0-9a-zA-Z/\-\?:\.,'\+ ]+$
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.
sourceAccount object, Required
The ClearBank account that will be debited based on the successful completion of the payment instruction. You need to include EITHER the iban field OR the schemeName and identification fields in this object.
debtor object, Required
creditorAccount object, Required
Party is owed an amount of money as the (ultimate) creditor. You need to include EITHER the iban field OR the schemeName and identification fields in this object.
creditor object, Required
purpose string
Underlying reason for the payment transaction, as published in an external purpose code list.
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.
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"
  },
  "sourceAccount": {
    "iban": "string",
    "schemeName": "BBan",
    "identification": "string"
  },
  "debtor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "string",
      "postCode": "string"
    },
    "lei": "string"
  },
  "creditorAccount": {
    "iban": "string",
    "schemeName": "BBan",
    "identification": "string"
  },
  "creditor": {
    "name": "string",
    "postalAddress": {
      "buildingNumber": "string",
      "buildingName": "string",
      "streetName": "string",
      "townName": "string",
      "country": "string",
      "postCode": "string"
    },
    "lei": "string"
  },
  "purpose": "Deposit",
  "categoryPurpose": "TradeSettlementPayment",
  "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 transactions that are internal transfers, this will not be unique, as the value specified in the two webhooks describing the transactions applied to the debtor and creditor accounts will match. Type: `string` Max. length:`35`
`Amount`	Transaction amount. Type: `int`
`TimestampSettled`	Date and time the transaction settled. Time Zone: `UTC` Type: `DateTime`
`TimestampCreated`	Date and time the transaction was created. Time Zone: `UTC` Type: `DateTime`
`CurrencyCode`	Optional Code of transaction currency. `GBP`
`DebitCreditCode`	Movement of transaction. Type: `string` Options:`Credit`, `Debit`
`Reference`	(optional) Payment transaction reference. Max. length: `140`
`IsReturn`	Is the Transaction returned from Scheme? `True` `False`
`Account`	Account information object Type: `object` It contains the `IBAN`, `BBAN`, `OwnerName`, `TransactionOwner` and `InstitutionName`. `IBAN`: International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN`: Basic Bank Account number associated with the account. Type: `string` Max. length: `30` Depending on Scheme Type `OwnerName`: name of the beneficiary account holder registered with ClearBank®. Type: `string` Max. length: `128` - Faster Payments = Sender’s Account Name - Chaps = Ordering Customer’s Name `TransactionOwnerName` Type: `string` Max. length: `128` - Beneficiary Account Holder, as specified by the remitter in the payment message. - For outbound payments, as specified by ClearBank® as the remitter name in the payment message. `InstitutionName`: The institution name. Max. length: `128` - Chaps = Ordering Institution
`CounterpartAccount`	The account which is not held at ClearBank. It contains the `IBAN`, `BBAN`, `OwnerName`, `TransactionOwner` and `InstitutionName`. `IBAN`(Optional): International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN`(Optional): Basic Bank Account number associated with the account. Type: `string` Max. length: `30` Depending on Scheme Type `OwnerName`: name of the beneficiary account. Type: `string` Max. length: `128` - Populated with either the same name as `TransactionOwnerName`, or with `“Not Provided”` depending on what is provided in the payment message. - Faster Payments = Beneficiary's Account Name `TransactionOwnerName` Type: `string` Max. length: `128` Populated by Scheme with the name provided in the payment message. - For outbound payments, this is populated as the Beneficiary Name which is provided by you. `InstitutionName`: The institution name. Max. length: `128` - Chaps = Beneficiary Institution
`ActualEndToEndTransactionId`	Unique payment Identifier depending on Scheme Type. Maximum Field Length: `255` Faster Payments = `FPID` Chaps = `Instruction Identification` FPID is the unique payment identifier generated by Faster Payments. Instruction Identification is the unique payment identifier generated by the remitting bank.
`DirectDebitMandateId`	(Optional) Unique Identification of a Direct Debit Instruction. Type: `GUID` Max. length: `36`
`TransactionCode`	(Optional) Direct Debit Transaction code: `"01"` - First collection `"17"` - Regular collection `"18"` - Re-presented collection `"19"` - Final collection (Optional) Direct Credit Transaction code: `"99"` - Standard Bank Giro Credit `"86"` - Bank to bank settlement `"Z4"` - Interest payment `"Z5"` - Dividend payment
`ServiceUserNumber`	(Optional) Service User's Unique Identifier registered with Bacs. Max. length: `6`
`BacsTransactionId`	(Optional) Type: `GUID` Max. length: `36`
`BacsTransactionDescription`	(Optional) `CreditTransactionSettled` `DebitContraTransactionSettled` `DebitTransactionSettled` `CreditContraTransactionSettled` `DirectDebitReceivedIndemnityClaimSettled`
`TransactionType`	(Optional) `DirectCredit` `DirectDebit` `DirectDebitIndemnityClaim`
`TransactionSource`	(Optional) Origination of the Transaction : Max. length: `50` Example: `CardProcessor`
`SupplementaryData`	(Optional) Transaction supplementary data It is an array with the a `Name` and `Value`. `Name`: Field Number/Name for an inbound CHAPS or FPS message. Max. length: `33` `Name` options: `20`, `13C`, `23B`, `23E`, `26T`, `32A`, `33B`, `36`, `50a`, `51A`, `52a`, `53a`, `54a`, `55a`, `56a`, `57a`, `59a`, `70`, `71A`, `71F`, `71G`, `72`, `77B`, `SendingFpsInstitution`, `Currency`, `DateSent`, `PaymentType`, `TransactionReferenceNumber`, `Amount`, `OriginatingCreditInstitution`, `OriginatingCustomerAccountNumber`, `OriginatingCustomerAccountName`, `OriginatingCustomerAccountAddress`, `EndToEndReference`, `BeneficiaryCreditInstitution`, `BeneficiaryCustomerAccountNumber`, `BeneficiaryCustomerAccountName`, `BeneficiaryCustomerAccountAddress`, `ReturnedPaymentFpId`, `PaymentReturnCode`, `PaymentSubTypeCode`, `PurposeTransactionType`, `TypeOfAccountCode`, `NumericReference`, `ReferenceInformation`, `RemittanceInformation`, `RegulatoryReporting`, `OriginalCurrency`, `OriginalAmount`, `ExchangeRate`, `ChargingInformation`, `SubmittingMember`, `ReceivingMember`, `SettlementCycleId`, `FileId`, `ProcessedAsynchronously`, `AgencyAccountWithMember`, `AgencySortCodeWithMember`, `RedirectedBeneficiaryCreditInstitution`, `RedirectedBeneficiaryCustomerAccountNumber`, `AbusiveMessageScreeningResult`, `AbusiveMessageScreeningIdentifiers` `Value` Max. length: `500` There could be more than one Name and Value pair.
`Iso20022XmlDocument`	(Optional) Only appears if `Scheme` is Chaps and the message type received is in ISO 20022 (MX) format. Content of the Document node (payload) of the received payment message, to enable processing of ISO 20022 messages for CHAPS. This value can be very long, so we recommend checking your firewall settings to ensure they will not prevent you from receiving the webhook. See below for examples. Type: `string` Min. Length: `0` Max. Length: `80000`
`Nonce`	Cryptographically secure number generated by ClearBank® for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example transaction settled webhook request body for Transfer scheme type

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

Example webhook response

{
    "Nonce": 949893874
}

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

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

This webhook confirms the payment assessment has failed.

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

Request body

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

Payload

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

Example payment message assessment failed webhook request body

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

Example webhook response

{
    "Nonce": 828803944
}

This webhook confirms the payment validation has failed.

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

Request body

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

Payload

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

Example payment message validation failed webhook request body

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

Example webhook response

{
    "Nonce": 1634549462
}

This webhook confirms the payment has been rejected.

Request body

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

Payload

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

Example transaction rejected webhook request body

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

Example webhook response

{
    "Nonce": 748392098
}

This webhook confirms that an inbound transaction has been held.

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

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

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

Request body

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

Payload

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

Example inbound transaction held webhook request body

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

Example webhook response

{
    "Nonce": 1082937278
}

This webhook confirms that an outbound transaction has been held.

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

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

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

Request body

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

Payload

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

Example outbound transaction held webhook request body

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

Example webhook response

{
    "Nonce": 1089558378
}

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 payment message format for CHAPS has recently changed. 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

CHAPS

CHAPS

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