Documentation
Understand the lifecycle. Build the connection.
Flominzo documentation for the payment lifecycle and reconciliation: the states a payment moves through, the evidence it needs, and the exceptions that keep it open.
Last updated:
Start where you need to
From instruction to closure
- Payment intent: capture what the customer or business wants to do.
- Plan and execution: decompose the instruction into controlled execution legs.
- Evidence: collect provider responses, callbacks, files, and bank records.
- Reconciliation: compare expected outcomes with independent evidence.
- Financial closure: close only when the required financial conditions are met.
Payment states
A payment has no single status. Each part of it has its own state, and the payment-level views are derived from them.
| State | Describes | Values |
|---|---|---|
| Attempt State | One instruction to one provider | RECORDED, SENT, ACCEPTED, PROCESSING, SUCCEEDED, FAILED, UNKNOWN, CANCELLED, REVERSED |
| Leg State | One unit of money movement in a plan | PLANNED, ROUTED, IN_PROGRESS, COMPLETED, FAILED, CANCELLED, REVERSED |
| Operational State | The payment, derived from its legs | ACCEPTED, COLLECTING, EXECUTING, PAID, PARTIALLY_PAID, FAILED, CANCELLED, REVERSED, PARTIALLY_REVERSED |
| Reconciliation State | How well the evidence agrees | UNRECONCILED, PARTIALLY_MATCHED, MATCHED, MISMATCHED |
| Settlement State | A counterparty settlement | EXPECTED, REPORTED, MATCHED, ACCEPTED, DISPUTED, ADJUSTED |
| Financial Closure | Whether the payment is proven | OPEN, FINANCIALLY_CLOSED, REOPENED |
UNKNOWN is never terminal. It is resolved by a status lookup, settlement evidence, or a recorded human decision, and never by sending the instruction again.
Evidence grades
Every evidence item records who produced it and how. For the question “did money move?”, a higher grade outranks a lower one. A disagreement is never silently discarded; it becomes an exception.
- CASH
- Bank movements, from a bank. The strongest proof that money moved.
- SETTLEMENT
- A counterparty’s statement of account: settlement reports, partner CSVs, PSP settlement files.
- CLAIM
- Operational status from a provider: API responses and webhooks.
- INTERNAL
- Flominzo’s own records: events, projections, and the ledger. Authoritative for what was instructed.
Exception types
| Exception | Example |
|---|---|
MISSING_CALLBACK | The provider accepted the payout, but no webhook or status change arrived in its declared window. |
CLAIM_MISMATCH | The API says paid; the webhook says failed. |
API_CSV_DISAGREEMENT | The API says paid; the daily file leaves the payment out or shows a different amount. |
SETTLEMENT_MISMATCH | A payment is claimed paid with no settlement evidence, or settlement totals do not agree. |
REVERSAL_AFTER_SUCCESS | The provider reverses a payment after reporting it paid. |
FEE_FX_MISMATCH | The applied fee or rate differs from the booked quote beyond tolerance. |
ORPHAN | Provider evidence with no matching attempt, or an attempt with no provider evidence. |
DUPLICATE | Two provider references or two settlement lines for one attempt. |
STALE_STATUS | A state has not changed beyond the expected window. |
FILE_MISSING | A declared file did not arrive by its cutoff. |
UNKNOWN_UNRESOLVED | An attempt stayed unknown beyond the lookup window; money sits in transit. |
POSITION_UNEXPLAINED | A ledger position has no corroborating evidence. |
POST_CLOSURE_EVIDENCE | New evidence arrived for a closed payment or day. |
Core concepts
- PaymentIntent
- The canonical expression of a requested payment.
- ExecutionLeg
- A defined part of a payment plan with its own execution and reconciliation state.
- Rail Profile
- Configuration describing a provider’s capabilities, mappings, formats, and behaviour.
- UNKNOWN
- An execution outcome that has not yet been established. Investigate before retrying.
- Evidence
- A source-linked record used to assess what actually happened.
- Financial closure
- The point at which the required financial evidence and controls agree. Late evidence may reopen it.
Guides
Prepare for a technical discussion
- Document your existing transaction identifiers and financial states.
- List providers, corridors, currencies, and settlement accounts.
- Identify APIs, webhooks, transaction sources, and available reports.
- Bring redacted sample files and the exceptions your team handles today.
- Agree data access, privacy requirements, and acceptance criteria.
Need environment-specific documentation?
Credentials, deployed schemas, configuration, and operational procedures are supplied for your integration environment. These public pages explain the common architecture and implemented read interfaces.
Request a technical walkthroughLet’s make it specific to you.
Bring your systems, payment flows, and questions. We’ll help define the next step.
Talk to the team