Account reporting
Statements
You can request a statement containing all payment activity across your ClearBank accounts for a completed business day, also referred to as a 'Bank to Customer Statement'. The statement is delivered in an ISO 20022 compliant XML file known as camt.053 (Cash Management message).
The statement is populated with transaction activity across all of your accounts within a given time range. Note that a transaction must be in a Settled state to be included. The startDateTime and endDateTime in your statement request must:
- be less than or equal to 25 hours apart
- be within the last 6 months (for example, on 1 July 2024, you can request transaction data back to and including 1 January 2024)
- be in the past
How to request and download your statement
Use the POST /v1/statementrequests endpoint to request the generation of a camt.053 statement for a specific time range.
The process is shown in this message flow diagram:
Once the statement has been generated, you will receive a Statements Ready For Download webhook containing a unique MessageId and a TotalPages value. The statement is divided into pages and each page is assigned a PageNumber value. If a page reaches the maximum number of accounts (5000), the statement is continued on a new page. Each page is a complete XML file starting with a group header.
To download a statement page, use the GET /v1/statements/{messageId} and provide the unique MessageID contained in the webhook and the PageNumber you wish to download. You can only download one statement page per request. If the generated statement contains multiple pages and you wish to download them all, repeat the GET call with an incremented page number until:
- PageNumber is equal to the TotalPages value in the webhook, or,
- LastPageIndicator in the Group Header of the XML is true
We'll respond to the GET statement call with a 200 OK response containing an XMLObject. This object contains the requested page of the camt.053 statement in XML format. The start of the statement page can be identified by the XML group header which will be in this format:
<?xml version="1.0" encoding="UTF-8" standalone="no"?><Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.053.001.11"><BkToCstmrStmt><GrpHdr><MsgId>1234567891234567891234567891234</MsgId><CreDtTm>2023-06-22T04:59:59.000Z</CreDtTm><MsgRcpt><Nm>Institution Name</Nm><Id><OrgId><Othr><Id>12345678901039488545</Id></Othr></OrgId></Id></MsgRcpt><MsgPgntn><PgNb>1</PgNb><LastPgInd>Yes</LastPgInd></MsgPgntn></GrpHdr>
Key camt.053 fields
There are many fields in camt.053 messages as defined in the ISO 20022 Standard. This table provides information on the most relevant fields within the messages and their associated conversions.
Group header
| Element | Data type | Min length | Max length | Level | Mandatory/Optional | Description |
|---|---|---|---|---|---|---|
| Group Header | N/A | N/A | N/A | +GrpHdr | Mandatory | Common information for the message. It only occurs once. |
| MessageIdentification | String | 1 | 35 | +GrpHdr ++MsgId | Mandatory | Point to point reference, as assigned by ClearBank, and sent to the account owner or the party authorised to receive the message, to unambiguously identify the message. The Message Identification has following pattern:<service> - Service name = CAMT053 <date> - Date in the format YYYYMMDD<time> - Time in the format hhmmssMs<random alphanumeric string> - 8 characters random alphanumeric stringRemark: ‘ _’ underscore segregates the elements |
| CreationDateTime | DateTime | N/A | N/A | +GrpHdr ++CreDtTm | Mandatory | Date and time when the message was created, time in UTC format (YYYY-MM-DDThh:mm:ss.sssZ) |
| MessagePagination | N/A | N/A | N/A | +GrpHdr ++MsgPgntn | Optional | Provides details on the page number of the message. |
| PageNumber | Numeric | 1 | 5 | +GrpHdr ++MsgPgntn +++PgNb | Optional | The Page Number, beginning with "1", is used to count the number of messages in a statement. |
| LastPageIndicator | Indicator | N/A | N/A | +GrpHdr ++MsgPgntn +++LastPgInd | Optional | Indicates the last page. True or False. |
| Message Recipient | N/A | N/A | N/A | +GrpHdr ++MsgRcpt | Optional | ClearBank client authorised by the account owner to receive information about movements on the account. |
| Name | String | 1 | 140 | +GrpHdr ++MsgRcpt +++Nm | Optional | Name of ClearBank's client. |
Statement
| Element | Data type | Min length | Max length | Level | Mandatory/Optional | Description |
|---|---|---|---|---|---|---|
| Identification | String | 1 | 35 | +GrpHdr ++MsgRcpt +++Id ++++OrgId +++++Othr ++++++Id | Optional | Your Institution ID |
| Identification | String | 1 | 35 | +Stmt ++Id | Mandatory | Unique ID per statement |
| FromDateTime | DateTime | N/A | N/A | +Stmt ++FrToDt ++FrDtTm | Optional | Date and time at which the period starts. |
| ToDateTime | DateTime | N/A | N/A | +Stmt ++FrToDt ++FrDtTm | Optional | Date and time at which the period ends. |
| IBAN | String | 22 | 34 | +Stmt ++Acct +++Id ++++IBAN | Optional | International Bank Account Number (IBAN) - identifier used internationally by financial institutions to uniquely identify the account of a customer. ISO 13616. |
| Code | Enum | 1 | 4 | +Stmt ++Acct +++Tp ++++Cd | Optional | Account type, in a coded form. ExternalCashAccountType1Code, default to CACC. |
| Name | String | 1 | 140 | +Stmt ++Acct +++Ownr ++++Nm | Optional | Name by which a party is known and which is usually used to identify that party. |
| BICFI | String | 8 | 11 | +Stmt ++Acct +++Svcr ++++FinInstnId +++++BICFI | Optional | Code allocated to a financial institution by the ISO 9362 Registration Authority (ClearBank's BIC). |
| Name | String | 1 | 140 | +Stmt ++Acct +++Svcr ++++FinInstnId +++++Nm | Optional | Name by which an agent is known and which is usually used to identify that agent (ClearBank) |
| Code | String | 1 | 4 | +Stmt ++Bal +++Tp ++++CdOrPrtry +++++Cd | Mandatory | Balance type, in a coded format. OPBD or CLBD (Opening or Closing Balance) |
| Amount | String | 0 | 18,5 | +Stmt ++Bal +++Amt | Mandatory | Amount of money of the cash balance e.g. <Amt Ccy="GBP">100.00</Amt> |
| CreditDebitIndicator | Enum | 4 | 4 | +Stmt ++Bal +++CdtDbtInd | Mandatory | Indicates whether the balance is a credit or a debit balance. A zero balance is considered to be a credit balance. CRDT or DBIT. |
| Currency Exchange | N/A | N/A | N/A | +Stmt ++Ntry +++AmtDtls ++++InstdAmt +++++CcyXchg | Optional | Set of elements used to provide details on the currency exchange |
| Source Currency | Enum | 3 | 3 | +Stmt ++Ntry +++AmtDtls ++++InstdAmt +++++CcyXchg ++++++SrcCcy | Optional | Currency from which an amount is to be converted in a currency conversion. |
| Target Currency | Enum | 3 | 3 | +Stmt ++Ntry +++AmtDtls ++++InstdAmt +++++CcyXchg ++++++TrgtCcy | Optional | Currency into which an amount is to be converted in a currency conversion. |
| Exchange Rate | Numeric | 0 | 11 (10 Fraction digits) | +Stmt ++Ntry +++AmtDtls ++++InstdAmt +++++CcyXchg ++++++XchgRate | Optional | Factor used to convert an amount from one currency into another. This reflects the price at which one currency was bought with another currency. |
| Code | Enum | 1 | 4 | +Stmt ++Ntry +++Sts ++++Cd | Optional | Entry status, in a coded form, always BOOK |
| Account Servicer Reference | String | 1 | 35 | +Stmt ++Ntry +++AcctSvcrRef | Optional | Unique reference as assigned by the account servicing institution to unambiguously identify the entry (ClearBank's TransactionId) |
| EndToEndIdentification | String | 1 | 35 | +Stmt ++Ntry +++NtryDtls ++++TxDtls +++++Refs ++++++EndToEndId | Optional | 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 (EndtoEndId) |
| InstructionIdentification | String | 1 | 35 | +Stmt ++Ntry +++NtryDtls ++++TxDtls +++++Refs ++++++InstrId | Optional | Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction. ActualEndToEndTransactionId for GBP payments else SchemeEndToEndId for MCCY |
| Ultimate Debtor | N/A | N/A | N/A | +Stmt ++Ntry +++NtryDtls ++++TxDtls +++++RltdPties ++++++UltmtDbtr | Optional | Party that initiated the payment that is reported in the entry. |
| Ultimate Creditor | N/A | N/A | N/A | +Stmt ++Ntry +++NtryDtls ++++TxDtls +++++RltdPties ++++++UltmtCdtr | Optional | Ultimate party to which an amount of money is due. |