camt.053.001.08 XSD schema and business logic

A camt.053.001.08 is a Bank to Customer Statement received by Mambu Payments to report all booked entries and balance information for one or more accounts over a given period. It is the primary message used for end-of-day cash reporting and reconciliation.

1. Message definition and structure

Access the message definition and structure here.

Document
└── BkToCstmrStmt (BankToCustomerStatement)
    ├── GrpHdr (GroupHeader)          — Message-level metadata
    └── Stmt [1..*] (Statement)       — One block per account or per period
        ├── Account identification
        ├── Bal [1..*] (Balance)      — Opening, closing, and optional interim balances
        └── Ntry [0..*] (Entry)       — One block per booked transaction
            └── NtryDtls (EntryDetails)   — Optional transaction-level detail
                └── TxDtls (TransactionDetails)

2. Business rules

2.1 Group Header (`GrpHdr`)

XML Tag	Name	Presence	Rules
`MsgId`	Message Identification	Mandatory	Must be unique per message. Maximum 35 characters.
`CreDtTm`	Creation Date and Time	Mandatory	ISO 8601 datetime (`YYYY-MM-DDThh:mm:ss`) indicating when the message was created. Always expressed in UTC.
`MsgRcpt`	Message Recipient	Optional	Identifies the account owner or authorised party receiving the statement.
`MsgPgntn`	Message Pagination	Optional	Present when the statement is split across multiple message files. Contains `PgNb` (page number) and `LastPgInd` (boolean indicating the final page).

2.2 Statement (`Stmt`)

Each Stmt block corresponds to one account for one reporting period.

XML Tag	Name	Presence	Rules
`Id`	Statement Identification	Mandatory	Unique identifier for this statement within the message.
`ElctrncSeqNb`	Electronic Sequence Number	Optional	Sequential counter incremented by one for each statement delivered for the same account. Allows the recipient to detect gaps or duplicate deliveries.
`CreDtTm`	Creation Date and Time	Optional	Datetime the statement was generated. If absent, the `GrpHdr/CreDtTm` applies.
`FrToDt`	From/To Date	Optional	The reporting period covered by this statement, expressed as a date range (`FrDtTm` and `ToDtTm`). Used when a single `Stmt` covers multiple business dates.
`Acct.Id.IBAN`	Account IBAN	Conditional	The IBAN of the account to which this statement belongs. Used to map each `Stmt` block to the correct internal or external account in your system.
`Acct.Id.Othr`	Account number (other format)	Conditional	The account number to which this statement belongs. Used to map each `Stmt` block to the correct internal or external account in your system.
`Acct.Ccy`	Account Currency	Optional	The currency of the account (ISO 4217 alpha code, e.g. `EUR`).
`Acct.Svcr`	Account Servicer	Optional	BIC of the institution servicing the account.

2.3 Balances (`Bal`)

Each Stmt must contain at least two balance entries: an opening booked balance and a closing booked balance. Additional balance types may be present.

Balance Type Code	Name	Presence	Description
`OPBD`	Opening Booked	Mandatory	The booked balance at the start of the reporting period. Equivalent to the prior day's closing booked balance.
`CLBD`	Closing Booked	Mandatory	The booked balance at the end of the reporting period, reflecting all entries included in this statement.
`CLAV`	Closing Available	Optional	The available balance at close, accounting for holds and pending items not yet booked.
`ITBD`	Interim Booked	Optional	A mid-period snapshot of the booked balance. Present when the statement covers multiple dates.
`ITAV`	Interim Available	Optional	A mid-period snapshot of the available balance.

Rules:

Bal.Amt must be a positive number. The sign of the balance is conveyed by Bal.CdtDbtInd (CRDT for a credit balance, DBIT for a debit/overdraft balance).
Bal.Dt must be present and must fall within the period covered by the statement.
The mathematical relationship OPBD + sum(Ntry.Amt for CRDT entries) − sum(Ntry.Amt for DBIT entries) = CLBD must hold.

2.4 Entries (`Ntry`)

Each Ntry represents one booked transaction on the account. An entry may group multiple underlying transactions into a single batch ; individual details are then available in the nested NtryDtls.TxDtls blocks.

XML Tag	Name	Presence	Rules
`NtryRef`	Entry Reference	Mandatory	A reference assigned by the bank. It is the user responsibility to value it properly to avoid duplicates in Mambu Payments system.
`Amt`	Amount	Mandatory	The amount of the entry in the account currency. Must be a positive value.
`CdtDbtInd`	Credit/Debit Indicator	Mandatory	`CRDT` for credit entries (funds received); `DBIT` for debit entries (funds sent).
`RvslInd`	Reversal Indicator	Optional	Set to `true` if this entry is a reversal of a previously booked entry.
`Sts`	Status	Mandatory	Always `BOOK` in a `camt.053` message. Entries in any other status are not included.
`BookgDt`	Booking Date	Optional (recommended)	The date the entry was posted to the account (`Dt` sub-element, format `YYYY-MM-DD`).
`ValDt`	Value Date	Optional (recommended)	The value date used for interest calculation. May differ from `BookgDt` (e.g. a Friday booking with a Monday value date).
`AcctSvcrRef`	Account Servicer Reference	Optional	The reference assigned to the entry by the account servicer. Useful for reconciliation and dispute resolution.
`BkTxCd`	Bank Transaction Code	Mandatory	Classifies the entry using the ISO 20022 External Bank Transaction Code three-level hierarchy: `Domn` (Domain), `Fmly` (Family), and `SubFmlyCd` (Sub-Family). See table below.
`AddtlNtryInf`	Additional Entry Information	Optional	Free-text field for supplementary information about the entry. Maximum 500 characters.

Bank Transaction Code (BkTxCd) — example values:

Domain	Family	Sub-Family	Description
`PMNT`	`RCDT`	any	Received Credit Transfer
`PMNT`	`RCDT`	`XBCT`	Received cross-border credit transfer
`PMNT`	`ICDT`	any	Issued Credit Transfer
`PMNT`	`ICDT`	`XBCT`	Issued cross-border credit transfer
`PMNT`	`RDDT`	any	Received Direct Debit
`PMNT`	`IDDT`	any	Issued Direct Debit

2.5 Entry Details and Transaction Details (`NtryDtls[#].TxDtls`)

When an entry contains multiple underlying transactions (batch), a NtryDtls block is present for each transaction. Each NtryDtls contains one or more TxDtls sub-blocks providing transaction-level granularity.

XML Tag	Name	Presence	Rules
`TxDtls.Refs.MsgId`	Original Message ID	Optional	The `MsgId` of the original payment message (e.g. a `pacs.008`) that gave rise to this entry.
`TxDtls.Refs.EndToEndId`	End-to-End Identification	Optional	The end-to-end reference from the original payment instruction. Preserved unchanged through the payment chain.
`TxDtls.Refs.UETR`	Unique End-to-End Transaction Reference	Optional	The UETR (UUID v4) assigned to the original payment, as defined in ISO 20022 and the SWIFT gpi standard.
`TxDtls.Amt.InstdAmt`	Instructed Amount	Optional	The original instructed amount, which may differ from the entry amount if a currency conversion or fee deduction occurred.
`TxDtls.CdtDbtInd`	Credit/Debit Indicator	Mandatory (if `TxDtls` present)	Must be consistent with the parent `Ntry.CdtDbtInd`.
`TxDtls.RltdPties`	Related Parties	Optional	Identifies the debtor, creditor, ultimate debtor, and ultimate creditor involved in the underlying transaction.
`TxDtls.RltdAgts`	Related Agents	Optional	Identifies the debtor agent and creditor agent involved in the underlying transaction.
`TxDtls.RmtInf`	Remittance Information	Optional	The payment reference or structured remittance data (e.g. creditor reference, invoice number) included in the original payment. Provided as `Ustrd` (unstructured, free text, max 140 characters) or `Strd` (structured, per ISO 11649 or proprietary scheme).

Rules:

When NtryDtls.Btch is present (batch entry), the sum of all TxDtls.Amt values must equal the parent Ntry.Amt.
TxDtls.Refs.UETR is populated for all entries derived from ISO 20022 payment messages. It is absent for entries originating from legacy MT-format messages that did not carry a UETR.
RmtInf.Ustrd and RmtInf.Strd are mutually exclusive within a single TxDtls block.

3. Mambu Payments business rules

3.1 Account identification

The account number (either IBAN or another format) must exactly match one of the declared connected accounts. If none is found, the statement will be ignored.

3.2 Creation of balances

There is no idempotency key for balances. Duplicates are allowed.

See here for the balance object definition at Mambu Payments.

3.3 Creation of transactions

The idempotency key is built from the entry reference: Ntry.NtryRef that must be unique (max 35 characters) and mandatory. In the case of two records with the same idempotency key, the second one will be discarded.

See here for the transaction object definition at Mambu Payments.

1. Message definition and structure

2. Business rules

2.1 Group Header (GrpHdr)

2.2 Statement (Stmt)

2.3 Balances (Bal)

2.4 Entries (Ntry)

2.5 Entry Details and Transaction Details (NtryDtls[#].TxDtls)