Import bank statements
The Bank Statement Import Wizard separates source preparation, parsing, preview, operator decisions and commit. This separation is essential: a file can be readable without being safe to commit, and a successful commit can still require reconciliation.
The verified import contract supports parser types csv, xlsx and pdf, source-specific mapping profiles, row diagnostics, ignored rows, a commit decision for warning rows and an idempotency key. Each committed row can retain a file identifier, download reference, file checksum, parser version, mapping profile ID, original row index and row hash.
Audience: treasury preparers, accountants, implementers, support analysts and auditors
Learning time: 55 minutes
Navigation: Finance → Bank statements → Import statement
Control objective: make every committed bank line reproducible from a retained source row without creating duplicate imports or silently accepting invalid data.
Learning outcomes
You will be able to:
- prepare a controlled source package before upload;
- choose a parser and mapping profile without guessing;
- explain parse, preview and commit as separate operations;
- interpret accepted, warning, error and ignored row outcomes;
- verify normalized dates, amounts, currencies, directions and references;
- decide whether warning rows may be included;
- use idempotency and provenance to prevent duplicate economic evidence;
- reconcile commit summaries to the source file;
- collect support evidence when a parser or mapping fails.
Exact definition and boundaries
A parser reads the source representation. A mapping profile maps source keys or columns to Makronexus target fields. A preview validates and normalizes rows but does not necessarily commit them. A commit creates the import and accepted transaction records under an idempotency key.
| Stage | Input | Output | Mutation? |
|---|---|---|---|
| Source preparation | bank file and statement metadata | approved source package | no Makronexus mutation |
| Parse | raw rows, parser type, mapping profile | mapped row candidates and diagnostics | no committed transaction |
| Preview | import draft and candidate rows | normalized rows, confidence, warnings/errors | no committed transaction |
| Operator decision | preview result | include, correct or ignore decision | no committed transaction |
| Commit | import draft, approved rows and options | import ID and commit summary | creates persistent evidence |
| Reconciliation | committed transactions and internal records | matches, discrepancies and review evidence | separate workflow |
Do not describe PDF support as universal OCR capability. The contract accepts pdf as a parser type, but actual layouts, mapping profiles and extraction quality remain source-specific.
Provenance model
| Provenance field | Why it matters |
|---|---|
file_id | stable storage identity for the retained statement |
download_url | controlled retrieval reference; access must remain protected |
checksum | detects source-file changes and duplicate submissions |
parser_version | explains changes in extraction behaviour |
mapping_profile_id | identifies the mapping rules used |
row_hash | supports row-level duplicate and re-performance checks |
original_row_index | links normalized data to the original source position |
A file name is not a checksum, and a visual row number is not a stable row hash.
Mapping profiles
A mapping profile contains a source system, parser type, name, default flag, version and mappings from source keys to target fields.
| Target field | Required meaning |
|---|---|
| Transaction date | booking date recognized by the source |
| Value date | optional clearing/effective date |
| Amount | numeric amount represented by the row |
| Currency | explicit row or statement currency |
| Transaction type | normalized credit/debit direction or preserved source code |
| Reference | source reference useful for matching |
| Description | source narrative |
| Metadata | additional source-specific evidence |
Before using a profile, confirm that its source system and parser type match the current file. A default profile is a convenience, not proof that the bank has not changed its export layout.
Parse, preview and commit sequence
Row outcome model
| Outcome | Meaning | Commit rule |
|---|---|---|
accepted | row passes required normalization and validation | eligible for commit |
warning | row is usable but requires operator review | committed only when warning inclusion is authorised |
error | row is invalid or unsafe | must not be committed as a valid transaction |
ignored | row is intentionally excluded | retain reason/provenance but do not create a transaction |
The preview summary exposes total, accepted, warning, error and ignored counts. The commit summary exposes committed and skipped counts in addition to warning/error/ignored totals. These numbers must be reconciled, not merely displayed.
Prerequisites
| Requirement | Why it matters |
|---|---|
| Approved source institution and bank account | prevents a valid file being attached to the wrong school account |
| Correct school selected | import draft is school-scoped |
| Exact statement reference and date | forms the statement identity |
| Confirmed opening and closing balances | provides import control totals |
| Confirmed currency design | prevents accidental cross-currency normalization |
| Retained source file and checksum | supports duplicate prevention and audit re-performance |
| Supported parser and tested mapping profile | makes transformation repeatable |
Importer with bank_statement_import:create | required for final creation |
| Reviewer with read/list abilities | independently verifies commit evidence |
| Incident path for parser failures | prevents unsafe manual workarounds |
Roles and exact permissions
| Action | Exact ability | Control |
|---|---|---|
| List mapping/import results in the workspace | bank_statement_import:list | scope to the selected school |
| Inspect a committed import | bank_statement_import:read | protect file access |
| Commit a new import | bank_statement_import:create | use a stable idempotency key |
| Correct import lifecycle status | bank_statement_import:update | reason and reviewer evidence required |
| List committed lines | bank_statement_transaction:list | reconcile counts and totals |
| Read one committed line | bank_statement_transaction:read | inspect row provenance and status |
| Append approved lines | bank_statement_transaction:create | not allowed after archival |
| Correct line status or payment link | bank_statement_transaction:update | do not use to bypass matching controls |
| Review bank-account configuration | school_bank_setting:read | prove the destination account |
| List bank accounts/providers | school_bank_setting:list | choose only active approved configuration |
| Update source configuration | school_bank_setting:update | configuration change is separate from import repair |
Prepare the source package
Before upload, create a source-control record containing:
- school and bank account;
- source system or export channel;
- statement period and reference;
- file name, size, format and checksum;
- opening and closing balances;
- currency and any multi-currency caveat;
- received timestamp and person;
- expected row count;
- whether headers, footers, balances or summary rows are included;
- approved mapping profile and version.
Do not edit the original file to “make it work.” When transformation is required, preserve the original and retain a controlled transformed copy with a reason.
Guided procedure
1. Search before importing
Open Bank statements and search the statement reference, source system and date.
Expected result: no authoritative completed or processing import exists for the same source package.
Control: if an import exists, investigate it before retrying.
2. Start the wizard
Choose Import statement with bank_statement_import:create. Select or enter the bank/source identity and parser type.
Expected result: the wizard displays the import draft and parser configuration.
Control: do not choose CSV merely because the file can be opened as text.
3. Select a mapping profile
Use the approved source-specific mapping profile. Confirm profile version and inspect mapped target fields.
Expected result: transaction date, amount, reference and other required fields map to the correct source columns.
Control: a changed bank header name can map the wrong data without producing a file-read failure.
4. Parse the source
Submit raw rows for parsing.
Expected result: mapped candidates and diagnostics appear.
System effect: no persistent transaction has been created.
5. Review preview diagnostics
For every row, inspect status, confidence, warnings, errors, normalized values and original row index.
Expected result: totals by status equal the source row population.
Control: confidence is decision support, not approval.
6. Correct or ignore safely
Correct the mapping or source interpretation for errors. Mark non-transaction rows such as approved headers as ignored. Document every manual decision.
Expected result: no unexplained error row remains in the commit population.
7. Reconcile normalized totals
Compare normalized row count, credit/debit or signed totals, currency and date range to the statement. Test:
opening balance + net statement movement = closing balance
Use the bank’s sign and direction rules. Do not force the formula to balance by changing an unexplained row.
8. Decide on warning rows
Set include_warning_rows only when an authorised reviewer has determined that each warning row is valid and traceable.
Expected result: warning inclusion is explicit, not accidental.
9. Commit with idempotency
Use a stable idempotency key derived from the controlled import request—not a random value generated for every retry.
Expected result: the response returns the import identity and summary.
Control: changing the idempotency key to overcome an uncertain timeout can create duplicate evidence.
10. Reconcile the commit summary
Verify:
- total rows;
- committed rows;
- skipped rows;
- warning rows;
- error rows;
- ignored rows;
- import ID, tenant, school, source and status;
- committed transaction totals.
11. Retain an evidence pack
Store the source checksum, parser version, mapping profile, preview summary, operator decisions, commit request identity, response summary and request ID.
Import field reference
| Field | Meaning | Required | Validation/control |
|---|---|---|---|
| School | owner of the import | yes | match selected context |
| Source system | bank/export identity | yes | use controlled code |
| Statement reference | external statement identity | yes | duplicate-check |
| Statement date | statement header date | contract-specific | validate date semantics |
| Opening/closing balance | statement control totals | optional in API | required by school policy where available |
| Currency | statement currency | yes | use approved three-letter code |
| File URL | retained source reference | controlled | protect access and expiry |
| Parser type | csv, xlsx or pdf | yes for wizard | confirm layout support |
| Mapping profile | versioned source-to-target rules | source-dependent | do not silently default |
| Idempotency key | commit request identity | yes in commit options | stable across exact retries |
Worked scenario: Mupfure Learning Academy
Mupfure receives an XLSX statement from its primary bank. The source package contains 212 visible rows, including one title row, one opening-balance row and one closing-balance row. The approved mapping profile expects columns named Booking Date, Value Date, Narrative, Reference, Debit, Credit and Currency.
The bank changed Booking Date to Transaction Date. The old profile maps no date and produces 209 error rows. The implementer does not edit the original statement. They create and test a new profile version, rerun preview, and obtain 207 accepted transaction rows, two warnings for blank references and three ignored non-transaction rows.
The reviewer confirms the two warning rows using amount, value date and narrative. The commit includes warning rows under one stable idempotency key. The returned committed count is 209 and skipped count is three. The team retains both profile versions and the preview evidence because the mapping change explains why the first preview failed.
Failure modes
| Symptom | Likely cause | Evidence to inspect | Safe action | Escalate when |
|---|---|---|---|---|
| Most rows have missing dates | changed column header or profile | raw keys and mapping version | correct/test mapping profile | source layout is ambiguous |
| Amounts are inverted | debit/credit mapping or sign convention | source columns and normalized direction | correct mapping; rerun preview | committed rows already affected |
| PDF rows merge or split | layout not supported by parser | parser diagnostics and original page | use approved alternate source export | no reproducible extraction exists |
| Duplicate commit after timeout | new idempotency key used on retry | request keys and import search | stop; identify authoritative import | duplicate rows reached reconciliation/accounting |
| Warning rows committed unintentionally | include option enabled without review | commit options and warning diagnostics | quarantine affected import and review | wrong amounts/dates were stored |
| Row totals do not equal source | ignored headers misunderstood or rows omitted | original indexes and summary | reconcile every row classification | untraceable difference remains |
| File URL no longer works | signed link expired | storage file ID and retention evidence | regenerate controlled access | original file is unavailable |
| Currency normalization is wrong | statement or row currency mapping | import draft and normalized rows | correct before commit | multi-currency source cannot be represented |
| Commit rejected | errors remain or required identity missing | preview rows and API error details | correct request; reuse exact retry identity | service returns inconsistent diagnostics |
Verification checklist
- Source file is preserved unchanged.
- File checksum and file ID are recorded.
- School, bank account, source system and statement reference are correct.
- Parser type matches the actual source.
- Mapping profile and version are approved.
- Every source row has an accepted, warning, error or ignored outcome.
- No error row is included in the commit.
- Every warning row has a documented inclusion decision.
- Normalized dates, amounts, currencies, directions and references are sampled.
- Opening/closing movement and row totals are reconciled.
- Stable idempotency is used for exact retries.
- Commit summary equals the approved population.
- Provenance is retained for every committed row.
- Reviewer can reproduce the result from the evidence pack.
Practice and knowledge check
Guided practice: create a twelve-row CSV with one title row, one invalid date and one missing reference. Build a mapping, preview it, classify every row and commit only the approved population.
Independent scenario: a PDF preview has 98% confidence but the total amount differs from the statement by USD 500. Decide whether to commit and list the evidence required.
- Why are parse and preview separate from commit?
- What does a mapping profile version explain?
- What is the difference between a warning and an error?
- Why is confidence not approval?
- What does a row hash support?
- When may warning rows be committed?
- Why must the same idempotency key be reused for an exact retry?
- What must be reconciled after commit?
Answer guide: the early stages are non-committing validation; profile versions explain transformation rules; warnings are reviewable while errors are unsafe; confidence cannot replace control totals; row hashes support provenance/duplicate checks; warnings require authorised evidence; stable retry identity prevents duplicates; counts, totals, scope, import identity and every skipped row must be verified.
Next lesson
Continue to Match and reconcile.