---
title: "CHAPS"
metaTitle: "CHAPS"
order: 5
showPageMenu: true
---

import EndpointBlock from "src/components/endpoint-block"
import WebhookPlaceholder from 'src/components/webhook-placeholder'
import Callout from "src/components/callout";
import ExternalLink from 'src/components/external-link';

## CHAPS

<Callout colour="blue"><h2>Deprecation notice</h2>
<p>The following endpoints were deprecated on <strong>13 May 2026</strong>:<br />
- <strong>POST /payments/chaps/v5/customer-payments</strong><br />
- <strong>POST /payments/chaps/v5/return-payments</strong><br />
- <strong>POST /payments/chaps/v5/institution-payments</strong><br /></p>

<p>These endpoints will continue to be supported until further notice. An updated removal date will be communicated once we have clarity from SWIFT and the Bank of England on their 2027 scope, enabling us to confirm when these endpoints can no longer be supported. Version 6 of these endpoints is now available. Please reach out to your Client Director with any questions.</p> <p>You can refer to our <a href="../api/versioning">versioning policy</a> and <a href="../api/support-life-cycle">support lifecycle information</a>.</p></Callout>

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.

You can 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/v6/customer-payments](#send-a-chaps-payment) endpoint.
- Settlement details are provided to you via the [Transaction Settled](#transaction-settled-webhook) webhook. 
- If you need to return a CHAPS payment, you can do so using the [POST /payments/chaps/v6/return-payments](#return-a-chaps-payment) endpoint.

<Callout colour="blue">
  It is important to verify your firewall and security settings to ensure that they do not block <a href="#transaction-settled-webhook">Transaction Settled webhook</a> notifications, which can include a large payload due to the size of the Iso20022XmlDocument field. <br/><br/>If ClearBank has successfully processed a notification but your system rejects it (for example, with a 403 response due to a firewall or security restriction), we will not reprocess or replay that notification. To retrieve settlement details, use the existing <a href="../gbp-accounts/transaction-data">GET transaction endpoint</a>. You can also find the transaction in the ClearBank Portal and access the full ISO 20022 message there.
</Callout>

The latest versions of the CHAPS endpoints support the new ISO20022 payment message formats. See [FIN to ISO20022 field mapping](#fin-to-iso-20022-field-mapping) for guidance on how the previous MT numbered field values map to the new ISO20022 XML tags.

### What's changed in version 6
The version 6 endpoints introduce the changes required to remove unstructured address types, together with a small number of ClearBank enhancements. If you are migrating from version 5, the key differences are:

**Customer payments (pacs.008) — `POST /payments/chaps/v6/customer-payments`**
- The Creditor's `postalAddress` is now **mandatory** (optional in v5). This enriches payment information with additional creditor details to reduce follow-on queries, improve STP processing, and future-proof you for upcoming scheme-mandated requirements.
- On the `Other` account identification block for `sourceAccount`, `debtorAccount` and `creditorAccount`: `schemeName` is now enforced and the legacy `proprietary` field has been removed.
- The amount field has been renamed from `instructedAmount` to `interBankSettlementAmount` to more accurately align with ISO 20022 wording.

**Institution / bank-to-bank payments (pacs.009) — `POST /payments/chaps/v6/institution-payments`**
- On the `Other` account identification block for `sourceAccount` and `creditorAccount`: `schemeName` is now enforced and the legacy `proprietary` field has been removed.
- The amount field has been renamed from `instructedAmount` to `interBankSettlementAmount`.

<Callout colour="blue">
For BoE funding clients: the new v6 and current v5 endpoints, as well as all Institution Portal screens, remain available until <strong>17:55</strong> UK time. We recommend that clients who complete Bank of England account funding through the ClearBank Portal screens integrate with the pacs.009 v6 endpoint to offer an alternative means of submitting these payments.
</Callout>

**Return payments (pacs.004) — `POST /payments/chaps/v6/return-payments`**
- A new optional `additionalInformation` field (105 characters) has been added to allow reason context to be supplied with a return. This field is **required** when the return reason code is `NARR`.

### Hybrid address

From 24 November 2025, some inbound CHAPS payments may include a new address format called hybrid address. A hybrid address is an address format that includes both structured fields (such as town name and country) and unstructured address lines.

The structured and unstructured address formats will also continue to be used alongside the hybrid address format. These formats appear in the `Iso20022XmlDocument` field in the [Transaction Settled webhook](#transaction-settled-webhook).

Hybrid address is being introduced as part of the Bank of England’s CHAPS updates to harmonise payment standards across jurisdictions in line with the Cross Border Payment Reporting Plus (CBPR+) requirements.

Each format has different requirements:
- Hybrid address formats contain up to two `<AdrLine>` XML tags of up to 70 characters each, alongside mandatory `<TwnNm>` and `<Ctry>` address tags
> Information received in the `<AdrLine>` XML tags should be distinct from what is received in the structured address elements. If a payment message contains duplicate information across structured and unstructured fields, we expect it will be rejected by the Bank of England.
- Unstructured address formats contain up to three `<AdrLine>` XML tags of up to 35 characters each

You can extract all address information from `<AdrLine>` XML tags, regardless of whether you receive a hybrid or unstructured address.

Ensure your systems can process hybrid address formats for inbound payments. No changes are required for outbound payments as they already use structured address.

Here is an example hybrid address:
```
<Nm>Jane Doe</Nm>
<PstlAdr>
  <TwnNm>Chicago</TwnNm>
  <Ctry>US</Ctry>
  <AdrLine>222 Merchandise Plaza 20th Floor Suite 2024, IL 60654</AdrLine>
</PstlAdr>
```

### Version 6 mandatory fields
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: <ExternalLink href="https://www.bankofengland.co.uk/-/media/boe/files/payments/rtgs-renewal-programme/iso-20022/uk-recommended-purpose-code-list.pdf">UK recommended Purpose Code PDF</ExternalLink>.  

#### Legal Entity Identifier (LEI)
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.

#### Purpose Codes and Category Purpose Codes
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.

<Callout colour="blue">
ClearBank are mandated to prioritise identifying which payments are linked to Property – therefore if you are looking to complete a property-related payment, ensure that you make use of these Purpose Codes in your payment instruction.
</Callout>

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 |  

#### Common use case examples

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 |

#### Populating the Creditor field in pacs.008 messages

The Creditor field in CHAPS pacs.008 messages identifies the party receiving the funds. This party may be an **individual**, a **business**, or a **financial institution**. The correct population of this field is essential for accurate payment routing and compliance with ISO 20022 standards.

<Callout colour="blue">
The <strong>CreditorAgent</strong> field is not required in the CHAPS pacs.008 endpoint, as this information can be inferred from the UK sort code.
</Callout>

Depending on the creditor type, you will need to populate either the `PrivateIdentifier` or `OrganisationIdentifier` block within the `Creditor` object:

|Creditor type	|Creditor object population	| Creditor name field population |
|---------------|---------------------------|--------------------------------|
|Individual	|PrivateIdentifier	| Full name of the individual |
|Business	|OrganisationIdentifier	| Registered business name |
|Financial institution	|OrganisationIdentifier	| Institution name (if acting as creditor)|

### Pacs.009 defund payment timing
If you are a Reserve Account Holder (RAH) and use BERTI to set up future-dated or future-timed pacs.009 defund payments from your Bank of England Reserve Account to your ClearBank account, you must specify a payment time no earlier than **06:00**.
  
If no time is specified, the payment defaults to when the Bank of England system opens. After an industry release, this may be before 06:00. In alignment with Bank of England rules, CHAPS BAU (Business as Usual) traffic must not be sent before 06:00.

**Please note:** This only applies to payments initiated by you in the Bank of England system and sent to your ClearBank account (defunding scenario). There is no impact to outbound CHAPS pacs.009 payments sent from ClearBank.


<EndpointBlock
    type="post"
    title="Send a CHAPS payment"
    endpoints={[
        {
        path: "/payments/chaps/v6/customer-payments",
        version: "6.0-CHAPS",
        webhooks: [
        'transaction-settled-webhook-v6',
        'payment-message-assessment-failed-webhook-v1',
        'payment-message-validation-failed-webhook-v1',
        'transaction-rejected-v2'
        ]
    },
        {
        path: "/payments/chaps/v5/customer-payments",
        version: "5.0.Chaps-payment",
        webhooks: [
        'transaction-settled-webhook-v6',
        'payment-message-assessment-failed-webhook-v1',
        'payment-message-validation-failed-webhook-v1',
        'transaction-rejected-v2'
        ]
    }
    ]}
/>

<EndpointBlock
    type="post"
    title="Return a CHAPS payment"
    endpoints={[
        {
        path: "/payments/chaps/v6/return-payments",
        version: "6.0-CHAPS",
        webhooks: [
        'transaction-settled-webhook-v6',
        'payment-message-assessment-failed-webhook-v1',
        'payment-message-validation-failed-webhook-v1',
        'transaction-rejected-v2'
        ]
    },
        {
        path: "/payments/chaps/v5/return-payments",
        version: "5.0-ChapsReturn",
        webhooks: [
        'transaction-settled-webhook-v6',
        'payment-message-assessment-failed-webhook-v1',
        'payment-message-validation-failed-webhook-v1',
        'transaction-rejected-v2'
        ]
    }
    ]}
/>

<Callout colour="blue">
The availability of the <strong>POST /payments/chaps/v6/institution-payments</strong> endpoint has been extended until <strong>17:55</strong> UK time. This aligns with the Bank of England funding screen currently provided to clients in the ClearBank Portal.
</Callout>

<EndpointBlock
    type="post"
    title="Send a CHAPS bank-to-bank payment"
    endpoints={[
        {
        path: "/payments/chaps/v6/institution-payments",
        version: "6.0-CHAPS",
        webhooks: [
        'transaction-settled-webhook-v6',
        'payment-message-assessment-failed-webhook-v1',
        'payment-message-validation-failed-webhook-v1',
        'outbound-held-transaction-v1',
        'transaction-rejected-v2'
        ]
    },
        {
        path: "/payments/chaps/v5/institution-payments",
        version: "5.0_BankToBank",
        webhooks: [
        'transaction-settled-webhook-v6',
        'payment-message-assessment-failed-webhook-v1',
        'payment-message-validation-failed-webhook-v1',
        'outbound-held-transaction-v1',
        'transaction-rejected-v2'
        ]
    }
    ]}
/>

<WebhookPlaceholder render='transaction-settled-webhook-v6' />
<WebhookPlaceholder render='payment-message-assessment-failed-webhook-v1' />
<WebhookPlaceholder render='payment-message-validation-failed-webhook-v1' />
<WebhookPlaceholder render='transaction-rejected-v2' />
<WebhookPlaceholder render='inbound-held-transaction-v1' />
<WebhookPlaceholder render='outbound-held-transaction-v1' />

## CHAPS simulation endpoints

<Callout colour="blue"><h2>Deprecation notice for sim</h2>
<p>The following endpoints were deprecated on <strong>13 May 2026</strong>:<br />
- <strong>POST /inbound-payment-simulation/chaps/v2/customer-payments</strong><br />
- <strong>POST /inbound-payment-simulation/chaps/v2/return-payments</strong><br />
- <strong>POST /v2/inbound-payment-simulation/return-payment-simplified</strong><br />
- <strong>POST /inbound-payment-simulation/chaps/v2/institution-payments</strong><br /></p>

<p>These endpoints will continue to be supported until further notice. An updated removal date will be communicated once we have clarity from SWIFT and the Bank of England on their 2027 scope, enabling us to confirm when these endpoints can no longer be supported. Please reach out to your Client Director with any questions.</p>

<p>You can refer to our <a href="../api/versioning">versioning policy</a> and <a href="../api/support-life-cycle">support lifecycle information</a>.</p></Callout>

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

Version 3 of the simulator endpoints for inbound CHAPS payments is now available. Version 3 removes support for unstructured address types. While SWIFT and the Bank of England are no longer mandating the implementation of some of these changes as part of the November 2026 industry update, we've chosen to proceed with these enhancements to align with evolving industry best practice and help clients prepare for future changes.

<Callout colour="blue">
    Outbound CHAPS payments sent via ClearBank already use structured address formatting. No changes are required to your outbound integration.
</Callout>

Please update your test integration to ensure continued compatibility with the hybrid address format.

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

<Callout colour="blue">
    The <a href="../gbp-payments/chaps#simulate-a-chaps-return-payment-using-a-simplified-request">POST /v2/inbound-payment-simulation/return-payment-simplified</a> endpoint has been deprecated. All requests through the new v3 <a href="#simulate-a-returned-chaps-payment">POST /inbound-payment-simulation/chaps/v3/return-payments</a> use a simplified request format.
</Callout>

<Callout colour="blue">
You should use the v3 API inbound simulator endpoints to simulate inbound CHAPS payments. Do not use the legacy web-based URL simulator.
</Callout>

#### What's changed in simulator version 3
If you are migrating from the version 2 simulator endpoints, the key differences are:

**Customer payments (pacs.008)**
- The amount field has been renamed from `instructedAmount` to `interBankSettlementAmount`.
- The Debtor `addressLine1` and `addressLine2` fields have been removed, as SWIFT's intention is to no longer support unstructured address formats.
- The Creditor `addressLine1` and `addressLine2` fields have been removed, as SWIFT's intention is to no longer support unstructured address formats.
- The `instructingAgentBIC` is now intelligently deduced from the Debtor details provided; a standard default value is used if not provided.
- If you supply an `instructingAgentBIC`, it is validated to ensure it is a valid CHAPS Direct Participant BIC.

**Institution payments (pacs.009)**
- The amount field has been renamed from `instructedAmount` to `interBankSettlementAmount`.
- The Debtor `addressLine1` and `addressLine2` fields have been removed, as SWIFT's intention is to no longer support unstructured address formats.
- The Creditor `addressLine1` and `addressLine2` fields have been removed, as SWIFT's intention is to no longer support unstructured address formats.
- The `instructingAgentBIC` is now intelligently deduced from the Debtor details provided; a standard default value is used if not provided.
- If you supply an `instructingAgentBIC`, this is validated to ensure it is a valid CHAPS Direct Participant BIC.

**Return payments (pacs.004)**
- The amount field has been renamed from `instructedAmount` to `returnedInterBankSettlementAmount`.
- A new optional `additionalInformation` field (105 characters) has been added. The `NARR` return reason code is supported when this field is populated.
- The `returnReasonCode` field has been renamed to `reason` to align with the outbound pacs.004 API endpoint.
- The `paymentId` in the request must reference an outbound CHAPS payment previously initiated in the simulation environment.


<EndpointBlock
    type="post"
    title="Simulate an inbound CHAPS payment"
    endpoints={[
    {
        path: "/inbound-payment-simulation/chaps/v3/customer-payments",
        version: "3.0-ChapsSim",
        webhooks: [
        'transaction-settled-webhook-v6',
        ]
    },
    {
        path: "/inbound-payment-simulation/chaps/v2/customer-payments",
        version: "2.0-ChapsSim",
        webhooks: [
        'transaction-settled-webhook-v6',
        ]
    }
    ]}
/>

### Examples of valid payloads

**Payload for a structured address**

```
{
  "InstructionIdentification": "12345678TEST1234567899100",
  "EndToEndIdentification": "12345678TEST12345678100",
  "InstructedAmount": {
    "Amount": 1001,
    "Currency": "GBP"
  },
  "InstructingAgentBic": "LOYDGB22XXX",
  "DebtorAccount": {
    "Iban": "GB71CPBK08929969687998"
  },
  "Debtor": {
    "Name": "Name 1",
    "PostalAddress": {
      "BuildingNumber": "No 12",
      "BuildingName": "LL House",
      "StreetName": "StreetName Value 5",
      "TownName": "TownName Value 6",
      "Country": "GB",
      "PostCode": "NN4 5QQ"
    },
    "OrganisationIdentifier": null,
    "PrivateIdentifier": null
  },
  "CreditorAccount": {
    "Iban": "GB86CLRB04056810005205"
  },
  "Creditor": {
    "Name": "Name 2",
    "PostalAddress": {
      "BuildingNumber": "No 27",
      "BuildingName": "AA House",
      "StreetName": "StreetName Value 20",
      "TownName": "TownName Value 21",
      "Country": "GB",
      "PostCode": "CC9 0FF"
    },
    "OrganisationIdentifier": null,
    "PrivateIdentifier": null
  },
  "Purpose": "CASH",
  "CategoryPurpose": "CASH",
  "RemittanceInformation": null
}
```

**Payload for a hybrid address**
```
{
  "InstructionIdentification": "12345678TEST1234567810011",
  "EndToEndIdentification": "12345678TEST1234567810011",
  "InstructedAmount": {
    "Amount": 1001,
    "Currency": "GBP"
  },
  "InstructingAgentBic": "LOYDGB22XXX",
  "DebtorAccount": {
    "Iban": "GB71CPBK08929969687998"
  },
  "Debtor": {
    "Name": "Name 1",
    "PostalAddress": {
      "BuildingNumber": "No 12",
      "BuildingName": "LL House",
      "StreetName": "StreetName Value 5",
      "TownName": "TownName Value 6",
      "Country": "GB",
      "PostCode": "NN4 5QQ",
      "AddressLine1": "57 Hello World Street, London, EC3A 1AB",
      "AddressLine2": "57 Hello World Street, London, EC3A 1AB"
    },
    "OrganisationIdentifier": null,
    "PrivateIdentifier": null
  },
  "CreditorAccount": {
    "Iban": "GB86CLRB04056810005205"
  },
  "Creditor": {
    "Name": "Name 2",
    "PostalAddress": {
      "BuildingNumber": "No 27",
      "BuildingName": "AA House",
      "StreetName": "StreetName Value 20",
      "TownName": "TownName Value 21",
      "Country": "GB",
      "PostCode": "CC9 0FF",
      "AddressLine1": "57 Hello World Street, London, EC3A 1AB",
      "AddressLine2": "57 Hello World Street, London, EC3A 1AB"
    },
    "OrganisationIdentifier": null,
    "PrivateIdentifier": null
  },
  "Purpose": "CASH",
  "CategoryPurpose": "CASH",
  "RemittanceInformation": null
}
```

<EndpointBlock
    type="post"
    title="Simulate a returned CHAPS payment"
    endpoints={[
    {
        path: "/inbound-payment-simulation/chaps/v3/return-payments",
        version: "3.0-ChapsSim",
        webhooks: [
        'transaction-settled-webhook-v6',
        ]
    },
    {
        path: "/inbound-payment-simulation/chaps/v2/return-payments",
        version: "2.0-ChapsSim",
        webhooks: [
        'transaction-settled-webhook-v6',
        ]
    }
    ]}
/>

<EndpointBlock
    type="post"
    title="Simulate a CHAPS return payment using a simplified request"
    endpoints={[
    {
        path: "/v2/inbound-payment-simulation/return-payment-simplified",
        version: "2.0-ChapsSim",
        webhooks: [
        'transaction-settled-webhook-v6',
        ]
    }
    ]}
/>

<EndpointBlock
    type="post"
    title="Simulate a CHAPS bank-to-bank payment"
    endpoints={[
        {
        path: "/inbound-payment-simulation/chaps/v3/institution-payments",
        version: "3.0-ChapsSim",
        webhooks: [
        'transaction-settled-webhook-v6',
        ]
    },
    {
        path: "/inbound-payment-simulation/chaps/v2/institution-payments",
        version: "2.0-ChapsSim",
        webhooks: [
        'transaction-settled-webhook-v6',
        ]
    }
    ]}
/>

## FIN to ISO20022 field mapping

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 <br/>_(MT103 successor)_|pacs.009 <br/>_(MT202 successor)_|pacs.004 <br/>_(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.<br/><br/>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\><br/><br/><IntrBkSttlmDt\>|<IntrBkSttlmAmt\><Ccy\><br/><br/><IntrBkSttlmDt\>|<RtrdIntrBkSttlmAmt\><Ccy\><br/><br/><IntrBkSttlmDt\>|
|:50A, F, or K|Ordering Customer (Payer)|Mandatory||This field specifies the customer ordering the transaction.|<Dbtr\><br/><br/><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<br/><br/><DbtrAgtAcct\> Supercedes Field 52a - Ordering Institution Account Number subfield|<Dbtr\> Supercedes Field 52a - Ordering Institution<br/><br/><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<br/><br/><CdtrAgtAcct\> Supercedes Field 57a – Account With Institution Account Number subfield|<CdtrAgt\> Supercedes Field 57a – Account With  Institution<br/><br/><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\><br/><br/><CdtrAcct\>|<RtrChain\><Cdtr\><Agt\>|
|:59 or 59A, F|Beneficiary|Mandatory||This field specifies the customer which will be paid.|<Cdtr\><br/><br/><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/<br/><br/><UltmtDbtr\> Supercedes Field 70 - preceded by codeword /ULTD/<br/><br/><UltmtCdtr\> Supercedes Field 70 - preceded by codeword /ULTB/<br/><br/><RltdRmtInf\> Supercedes Field 70 - preceded by codeword /RELID/<br/><br/><RmtInf\> Supercedes Field 70 - Remittance Information|<RmtInf\>||
|:71A|Details of Charges|Mandatory||This field specifies which party will bear the charges for the transaction.<br/><br/>Previous FIN charge codes:<br/>BEN - Beneficiary<br/>OUR - Our Customer charged<br/> SHA - Shared Charges|<ChrgBr\><br/> Borne by Creditor - CRED<br/>Borne by Debtor - DEBT<br/>Shared - SHAR||<ChrgBr\><br/> Borne by Creditor - CRED<br/>Borne by Debtor - DEBT<br/>Shared - SHAR|
|:72|Sender to Receiver Information|Optional|Optional|This field specifies additional information for the Receiver or other party specified.<br/><br/>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/<br/><br/> <PrvsInstgAgt1\><PrvsInstgAgt2\><PrvsInstgAgt3\> Supercedes Field 72 –  preceded by codeword /INS/<br/><br/><InstgAgt\> Sender<br/><br/><InstdAgt\>Receiver<br/><br/><IntrmyAgt2\><IntrmyAgt3\> Supercedes Field 72 –  preceded by codeword /INTA/<br/><br/><InstrForCdtrAgt\> Supercedes Field 72 – preceded by codeword /ACC/<br/><br/><InstrForNxtAgt\> Supercedes Field 72 – preceded by codeword /REC/<br/><br/>|<PmtTpInf\><LclInstrm\> Supercedes Field 72 – preceded by codeword /LOCINS/ Also CLS-specific codewords<br/><br/><PmtTpInf\><CtgyPurp\> Supercedes Field 72 – preceded by codeword /CATPURP/<br/><br/><PrvsInstgAgt1\><PrvsInstgAgt2\><PrvsInstgAgt3\> Supercedes Field 72 – preceded by codeword /INS/<br/><br/><IntrmyAgt2\><IntrmyAgt3\> Supercedes Field 72 – preceded by codeword /INTA/<br/><br/><DbtrAgt\> Supercedes Field 72 – preceded by codeword /INS/<br/><br/><InstrForCdtrAgt\> Supercedes Field 72 – preceded by codeword /ACC/, /PHONBEN/, /TELEBEN/<br/><br/><InstrForNxtAgt\> Supercedes Field 72 – preceded by codeword /REC/<br/><br/><Purp\> Supercedes Field 72 – preceded by codeword /PURP/<br/><br/><RmtInf\> Supercedes Field 72 – preceded by codeword /BNF/ or /TSU/<br/><br/>|<RtrRsnInf\><Rsn\><Cd\> Supercedes Field 72 - Sender to Receiver Info - Line 2<br/><br/><OrgnlEndToEndId\> Supercedes Field 72 - Sender to Receiver Info - Line 4<br/><br/><ChrgsInf\><Amt\> Supercedes Field 72 - Sender to Receiver Info - Line 5<br/><br/><OrgnlIntrBkSttlmDt\> Supercedes Field 72 - Sender to Receiver Info - Line 6|

## CHAPS return reason codes

The following table details the CHAPS return reason codes used to populate the `reason` field of the [Return a CHAPS payment](#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.                                                                                  |