...
# Requirements Specification – CAMT.054 Payments in ProBill
**Date:** 2026-03-04
**Scope:** Incoming payments and CAMT.054 outgoing payments. Pain.002 handling is covered by this specification above in this page.
---
## 1. Purpose and Scope
This requirements specification describes how ProBill interprets and stores payments from CAMT.054 files (ISO 20022 standard, message type `BkToCstmrDbtCdtNtfctn`, version `camt.054.001.02`).
**Included:**
- Identification of incoming and outgoing payment files
- Which XML tags are read
- Logic for calculating key variables (incoming payments)
- Mapping to `dbo.Payment` (incoming payments)
- Mapping to `dbo.LedgerPayoutResult` (outgoing payments)
- Error handling and status assignment (incoming payments)
---
## 2. Identification of File Type
A file is identified as CAMT.054 if the XML content contains the element name `BkToCstmrDbtCdtNtfctn`.
**XML namespace:**`urn:iso:std:iso:20022:tech:xsd:camt.054.001.02`
The file type is then determined by `GrpHdr/AddtlInf`:
| Condition | File type | Target table |
|---|---|---|
| `GrpHdr/AddtlInf` does not contain `DEBT` | Incoming payment | `dbo.Payment` |
| `GrpHdr/AddtlInf` contains `DEBT` | Outgoing payment | `dbo.LedgerPayoutResult` |
---
## 3. XML Structure and Tags Read
The CAMT.054 file has a hierarchical structure with three levels that are read:
```
Document/BkToCstmrDbtCdtNtfctn
├── GrpHdr ← Message header (one per file)
└── Ntfctn ← Notification / account (one or more per file)
├── Id
├── CreDtTm
├── Acct ← Receiver account
└── Ntry ← Transaction / entry (one or more per Ntfctn)
├── BookgDt/Dt
├── ValDt/Dt
└── NtryDtls/TxDtls ← Transaction details
├── Refs
├── AmtDtls
├── RltdPties ← Involved parties
├── Purp
├── RltdDts
└── RmtInf ← Remittance information
├── Ustrd
└── Strd ← Structured remittance (one or more)
```
### 3.1 Message Header – GrpHdr
Read once per file from `/Document/BkToCstmrDbtCdtNtfctn`.
| XML tag | Description |
|---|---|
| `GrpHdr/MsgId` | Unique message ID |
| `GrpHdr/CreDtTm` | Message creation date and time |
| `GrpHdr/AddtlInf` | Additional information. Used to distinguish incoming payments (no `DEBT`) from outgoing payments (`DEBT` present). |
### 3.2 Account Information – Ntfctn
Read per `Ntfctn` node. Represents the receiving account (seller's account).
| XML tag | Description |
|---|---|
| `Ntfctn/Id` | Unique notification ID. Mandatory per standard. Used to link the account to the correct transactions. |
| `Ntfctn/CreDtTm` | Notification creation date and time |
| `Ntfctn/Acct/Id/IBAN` | Receiver account IBAN number |
| `Ntfctn/Acct/Id/Othr/Id` | Receiver account BBAN (e.g. bankgiro number) |
| `Ntfctn/Acct/Id/Othr/SchmeNm/Cd` | Account scheme code (e.g. `BBAN`) |
| `Ntfctn/Acct/Ownr/Id/OrgId/Othr/Id` | Account owner organisation ID (e.g. organisation number) |
>
**Note:** A CAMT.054 file may contain multiple `Ntfctn` nodes. Each `Ntfctn` has a unique `Id` used to ensure each transaction is linked to the correct account.
### 3.3 Transaction Details – Ntry / TxDtls / Strd
Read per transaction. An `Ntfctn` can have multiple `Ntry` nodes, and each `Ntry` can have multiple `TxDtls` and/or `Strd` nodes.
>
Transactions without a `Strd` element are still included (e.g. Swish payments).
| XML tag | Description |
|---|---|
| `Ntfctn/Ntry/BookgDt/Dt` | Booking date |
| `Ntfctn/Ntry/ValDt/Dt` | Value date |
| `TxDtls/Refs/AcctSvcrRef` | Bank's internal transaction ID |
| `TxDtls/Refs/EndToEndId` | End-to-end reference. Used for Swish to identify the mobile number. |
| `TxDtls/AmtDtls/TxAmt/Amt` | Transaction amount |
| `TxDtls/AmtDtls/TxAmt/Amt/@Ccy` | Currency code for the transaction amount (XML attribute) |
| `TxDtls/RltdPties/Dbtr/Nm` | Payer name |
| `TxDtls/RltdPties/Dbtr/PstlAdr/StrtNm` | Payer street address |
| `TxDtls/RltdPties/Dbtr/PstlAdr/PstCd` | Payer postal code |
| `TxDtls/RltdPties/Dbtr/PstlAdr/TwnNm` | Payer city |
| `TxDtls/RltdPties/Dbtr/Id/OrgId/Othr/Id` | Payer organisation number |
| `TxDtls/RltdPties/DbtrAcct/Id/IBAN` | Payer account number (IBAN) |
| `TxDtls/RltdPties/DbtrAcct/Id/Othr/Id` | Payer account number (BBAN or other). Also used as Swish mobile number. |
| `TxDtls/RltdPties/DbtrAcct/Id/Othr/SchmeNm/Prtry` | Account scheme name for payer's account |
| `TxDtls/RltdPties/UltmtDbtr/Nm` | Ultimate debtor name (if different from Dbtr) |
| `TxDtls/RltdPties/UltmtDbtr/PstlAdr/StrtNm` | Ultimate debtor street address |
| `TxDtls/RltdPties/UltmtDbtr/PstlAdr/PstCd` | Ultimate debtor postal code |
| `TxDtls/RltdPties/UltmtDbtr/PstlAdr/TwnNm` | Ultimate debtor city |
| `TxDtls/RltdPties/UltmtDbtr/Id/OrgId/Othr/Id` | Ultimate debtor organisation number |
| `TxDtls/RltdPties/Cdtr/Nm` | Payee (creditor) name |
| `TxDtls/RltdPties/CdtrAcct/Id/IBAN` | Payee IBAN |
| `TxDtls/RltdPties/CdtrAcct/Id/Othr/Id` | Payee BBAN (bankgiro) |
| `TxDtls/Purp/Cd` | Payment purpose code. Used for Swish identificationSwish payments carry the code `WEBI`, `SUPP` or `REFU`. |
| `TxDtls/RltdDts/AccptncDtTm` | Acceptance date/time |
| `TxDtls/RmtInf/Ustrd` | Unstructured remittance message (free text) |
| `RmtInf/Strd/RfrdDocInf/Nb` | Invoice number |
| `RmtInf/Strd/RfrdDocAmt/CdtNoteAmt` | Credit note amount |
| `RmtInf/Strd/RfrdDocAmt/CdtNoteAmt/@Ccy` | Currency for credit note amount (XML attribute) |
| `RmtInf/Strd/RfrdDocAmt/RmtdAmt` | Remitted amount (actual amount paid) |
| `RmtInf/Strd/RfrdDocAmt/RmtdAmt/@Ccy` | Currency for remitted amount (XML attribute) |
| `RmtInf/Strd/CdtrRefInf/Ref` | OCR reference (payer's reference to the creditor) |
| `RmtInf/Strd/AddtlRmtInf` | Additional remittance information. May appear **multiple times** in the same `Strd` element – all repetitions are concatenated into a single text value. Used among other things for Swish payments (contains `OrderID:`). |
---
## 4. Logic for Key Variables
The following variables are calculated before mapping to the target table.
### 4.1 Swish Identification (IsSwish)
A payment is classified as Swish based on a combination of three signals:
| Signal (`IsSwish = 1`) if **both** of the following conditions are met:
**Condition 1 – Prerequisite (must be satisfied):**
-`TxDtls/Refs/EndToEndId` is NOT NULL
**Condition 2 – At least one of the following:**
| Check | XML source | Condition |
|---|---|
| Mobile number / reference | `ISNULL(TxDtls/Refs/EndToEndId, TxDtls/RltdPties/DbtrAcct/Id/Othr/Id)` |---|
| Free text contains order ID | `RmtInf/Strd/AddtlRmtInf` | Contains the string `'OrderID:'` |
| Purpose code is a Swish code | `TxDtls/Purp/Cd` |
Results in `IsSwish = 1` (Swish) or `IsSwish = 0` (not Swish) | Is one of: `WEBI`, `SUPP`, `REFU` |
If `EndToEndId` is NULL, `IsSwish = 0` is always returned regardless of other fields.
### 4.2 ReferenceID
Calculated using the following priority order (first non-empty value is used):
| Priority | Source | Comment |
|---|---|---|
| 1 | `RmtInf/Strd/CdtrRefInf/Ref` | OCR reference |
| 2 | `RmtInf/Strd/RfrdDocInf/Nb` | Invoice number |
| 3 | Extracted from `RmtInf/Strd/AddtlRmtInf` | **Only if IsSwish = 1:** the text between `'OrderID: '` and `'-'` is extracted. Swish messages contain an order ID formatted as `'OrderID: XXXXX-...'`. |
| 4 | `RmtInf/Strd/AddtlRmtInf` (if not Swish) | Used as reference if none of the above are present |
| 5 | `RmtInf/Ustrd` | Unstructured message as last resort |
### 4.3 Amount
Calculated using the following priority order:
| Priority | Source | Comment |
|---|---|---|
| 1 | `RmtInf/Strd/RfrdDocAmt/RmtdAmt` | Remitted amount – actual payment |
| 2 | `-` + `RmtInf/Strd/RfrdDocAmt/CdtNoteAmt` | Credit note amount stored with **negative sign** (credit note = refund) |
| 3 | `TxDtls/AmtDtls/TxAmt/Amt` | Transaction amount |
| 4 | `0` | Fallback if no amount is found (field is NOT NULL in target table) |
### 4.4 EntryDate (Booking Date)
```
EntryDate = Ntfctn/Ntry/BookgDt/Dt (NULL if empty)
```
### 4.5 PaymentDate
Calculated using the following priority order:
| Priority | Source |
|---|---|
| 1 | `TxDtls/RltdDts/AccptncDtTm` |
| 2 | `Ntfctn/Ntry/ValDt/Dt` |
| 3 | `Ntfctn/Ntry/BookgDt/Dt` |
---
## 5. Incoming Payments – Mapping to dbo.Payment
The table below shows exactly how each column in `dbo.Payment` is populated.
| Column | XML source / Logic |
|---|---|
| `FileID` | File ID (link to source file) |
| `Created` | `Ntfctn/CreDtTm` – converted to DATETIME2. Four conversion formats are tried in order. Fallback: `1900-01-01`. |
| `SellerReference` | `Ntfctn/Acct/Ownr/Id/OrgId/Othr/Id` – seller's organisation identification |
| `SellerAccount` | Receiver account formatted in priority order: IBAN prefixed with `[IBAN]`, otherwise BBAN prefixed with the scheme code e.g. `[BBAN] 12345678` |
| `EntryDate` | See §4.4. Fallback: `1900-01-01` (NOT NULL). |
| `PaymentDate` | See §4.5. Fallback: `1900-01-01` (NOT NULL). |
| `ArchiveID` | `TxDtls/Refs/AcctSvcrRef` – bank's internal transaction ID |
| `ReferenceID` | See §4.2. **Only if the value is numeric** – otherwise NULL (placed in Comment instead). |
| `Comment` | Populated according to three cases in priority order: (1) if ReferenceID is non-numeric: the non-numeric reference value, (2) if IsSwish = 1: `'Swish från mobilnummer 0'` + mobile number, (3) otherwise: NULL |
| `OCRMessage` | `RmtInf/Strd/AddtlRmtInf` – raw additional information. NULL if empty. |
| `PayeeName` | `UltmtDbtr/Nm` if present, otherwise `Dbtr/Nm` |
| `PayeeAddress` | `UltmtDbtr/PstlAdr/StrtNm` if present, otherwise `Dbtr/PstlAdr/StrtNm` |
| `PayeeZipCode` | `UltmtDbtr/PstlAdr/PstCd` if present, otherwise `Dbtr/PstlAdr/PstCd`. **Spaces are removed.** |
| `PayeeCity` | `UltmtDbtr/PstlAdr/TwnNm` if present, otherwise `Dbtr/PstlAdr/TwnNm` |
| `PayeeOrgNumber` | `UltmtDbtr/Id/OrgId/Othr/Id` if present, otherwise `Dbtr/Id/OrgId/Othr/Id` |
| `PaymentAccount` | Receiver account in priority order: (1) `CdtrAcct/Id/IBAN`, (2) `CdtrAcct/Id/Othr/Id` (bankgiro), (3) fallback to SellerAccount (if CdtrAcct is missing) |
| `PayeeAccount` | Payer account in priority order: (1) `[IBAN]` + `DbtrAcct/Id/IBAN`, (2) scheme code + `DbtrAcct/Id/Othr/Id`, (3) `DbtrAcct/Id/Othr/Id` |
| `Amount` | See §4.3. NOT NULL. |
| `Currency` | Currency code: `RmtdAmt/@Ccy` → `CdtNoteAmt/@Ccy` → `TxAmt/@Ccy` |
| `CurrencyID` | Currency ID via lookup on currency code |
| `ReturnMaterialCode` | NULL (not mapped) |
| `RecordCode` | `6` if IsSwish = 1 (Swish), otherwise `3` (BG/PG) |
| `CorrectionCode` | `0` (fixed value) |
| `SourceID` | `1` if SellerAccount matches a debt collection or post-watch account, otherwise `0` (bank) |
| `ErrorID` | See §6.1 |
| `StatusID` | See §6.2 |
| `Handled` | See §6.3 |
---
## 6. Incoming Payments – Error Handling and Status Assignment
### 6.1 ErrorID – Error Code
Checked in priority order – **first matching error** is used:
| Priority | Condition | ErrorID | Description |
|---|---|---|---|
| 1 | ReferenceID missing/non-numeric **and** Amount = 0 | `1` | Invoice not found |
| 2 | ReferenceID missing or non-numeric | `6` | Incorrect reference number |
| 3 | Amount = 0 | `38` | Unreasonable amount |
| 4 | SellerAccount is a post-watch account | `8` | Post-watch |
| 5 | EntryDate missing | `43` | Booking date missing |
| 6 | PaymentDate missing | `44` | Payment date missing |
| 7 | No errors | `NULL` | – |
### 6.2 StatusID – Status
| Condition | StatusID | Status |
|---|---|---|
| ReferenceID missing/non-numeric, **or** Amount = 0, **or** EntryDate missing, **or** PaymentDate missing | `2` | Error |
| None of the above | `0` | New |
### 6.3 Handled – Direct Flagging
Records with an identified error are marked as handled immediately upon import (Handled = current timestamp). This prevents a subsequent process from overwriting the specific error code with a more generic value.
**Records are flagged immediately if:** ReferenceID is missing/non-numeric, Amount = 0, EntryDate is missing, or PaymentDate is missing.
All other records are left unflagged (Handled = NULL) for further processing.
---
## 7. Outgoing Payments – Mapping to dbo.LedgerPayoutResult
### 7.1 Identification
A record is treated as an outgoing payment if `GrpHdr/AddtlInf` contains the string `DEBT`.
### 7.2 Link to LedgerPayout
The outgoing payment is linked to an existing payout order via:
-`TxDtls/Refs/EndToEndId` cast as integer → matched against `LedgerPayout.ID`
-`CustomerID` is retrieved from the matching `LedgerPayout` record
### 7.3 Mapping
The same XML tags described in section 3 are used. The table below shows how each column in `dbo.LedgerPayoutResult` is populated.
| Column | XML source / Logic |
|---|---|
| `FileID` | File ID (link to source file) |
| `Inserted` | Current timestamp at import |
| `Handled` | NULL on INSERT (processed further by a subsequent job) |
| `StatusID` | `2` (= Payout executed) |
| `FileDate` | `Ntfctn/CreDtTm` – converted to DATETIME. If direct conversion fails, conversion via DATETIMEOFFSET is attempted. |
| `PayerAccount` | `Ntfctn/Acct/Id/IBAN` if present, otherwise `Ntfctn/Acct/Id/Othr/Id` |
| `Reason` | NULL (not mapped) |
| `Amount` | Priority order: (1) `RmtInf/Strd/RfrdDocAmt/RmtdAmt`, (2) `-` + `RmtInf/Strd/RfrdDocAmt/CdtNoteAmt` (credit note stored with negative sign), (3) `TxDtls/AmtDtls/TxAmt/Amt` |
| `PayoutDate` | `Ntfctn/Ntry/ValDt/Dt` if present, otherwise `Ntfctn/Ntry/BookgDt/Dt` |
| `Name` | `TxDtls/RltdPties/Cdtr/Nm` |
| `PayeeAccount` | `TxDtls/RltdPties/CdtrAcct/Id/IBAN` if present, otherwise `TxDtls/RltdPties/CdtrAcct/Id/Othr/Id` |
| `PayoutID` | `TxDtls/Refs/EndToEndId` cast as integer → ID in `LedgerPayout` |
| `CustomerID` | Retrieved from the matching `LedgerPayout` record via `PayoutID` |
### 7.4 Post-processing
After INSERT, each outgoing payment record is marked as handled (Handled = current timestamp). If outgoing payment records were inserted, a subsequent process for result handling is triggered.
---
*Based on existing implementation in ProBill version: 2.0.4833.0. XML standard: ISO 20022 camt.054.001.02.*
---
...