NbOfTxs Mismatch in pain.001
NbOfTxs mismatches cause silent pain.001 rejections. Learn what the transaction count field means, the common off-by-one mistakes, and how to compute it correctly.
What NbOfTxs is
NbOfTxs (Number of Transactions) is a mandatory field in the GrpHdr block. It must equal the total count of CdtTrfTxInf (Credit Transfer Transaction Information) elements across all PmtInf blocks in the file.
Like CtrlSum, NbOfTxs is an integrity check. The bank counts the actual transactions in your file and compares against the declared value. A mismatch causes the entire file to be rejected.
NbOfTxs must match the actual count of CdtTrfTxInf elements
<GrpHdr>
<NbOfTxs>3</NbOfTxs> <!-- Must equal total CdtTrfTxInf count -->
<CtrlSum>300.00</CtrlSum>
</GrpHdr>
<PmtInf>
<CdtTrfTxInf>...</CdtTrfTxInf> <!-- 1 -->
<CdtTrfTxInf>...</CdtTrfTxInf> <!-- 2 -->
<CdtTrfTxInf>...</CdtTrfTxInf> <!-- 3 -->
</PmtInf>Common mistakes
The most frequent cause is building the file in multiple passes: a developer writes the transactions first, then fills in the header fields — but uses a stale count from before adding the final batch.
Another common mistake: counting PmtInf blocks instead of CdtTrfTxInf elements. Each PmtInf can contain multiple transactions. The NbOfTxs at GrpHdr level counts individual transactions, not payment groups.
Copy-paste errors during template reuse also cause mismatches: a template declares NbOfTxs=1 and the developer adds transactions without updating the header.
Multiple PmtInf blocks
NbOfTxs must count across all PmtInf blocks. This is the most common source of off-by-one errors in batch payment files.
Wrong vs correct NbOfTxs with multiple PmtInf
<!-- WRONG: NbOfTxs counts only first PmtInf -->
<GrpHdr>
<NbOfTxs>2</NbOfTxs> <!-- Only counted batch 1 -->
</GrpHdr>
<PmtInf> <!-- Batch 1: 2 transactions -->
<CdtTrfTxInf>...</CdtTrfTxInf>
<CdtTrfTxInf>...</CdtTrfTxInf>
</PmtInf>
<PmtInf> <!-- Batch 2: 1 transaction — missed! -->
<CdtTrfTxInf>...</CdtTrfTxInf>
</PmtInf>
<!-- CORRECT -->
<GrpHdr>
<NbOfTxs>3</NbOfTxs> <!-- 2 + 1 across both PmtInf -->
</GrpHdr>How to fix a NbOfTxs mismatch
Never set NbOfTxs manually based on an estimated count. Always compute it by counting CdtTrfTxInf elements in the fully assembled document before serialization.
In code: build the complete list of transactions first, then set NbOfTxs = transactions.length and CtrlSum = sum of all amounts. These two fields must always be the last to be written.
NbOfTxs and CtrlSum mismatches almost always occur together. Fixing one without checking the other is a common source of second-round rejections.