An API response can say that a request was accepted. A webhook can report a new payment status. Neither alone proves that the merchant received the expected amount, the order moved correctly, the internal ledger balanced, and the accounting export closed. Reliable payment systems preserve evidence across every layer.
Pix supports instant transfers around the clock, but an application still observes distinct moments: charge creation, customer authorization, payment instruction, clearing and settlement, credit to the receiving account, provider notification, internal ledger posting, order release, refund, and accounting close. Open Finance payment initiation adds consent and payment resources with their own state machines.
Do not collapse these into a single boolean named paid. Each transition has a source, identifier, event time, receive time, amount, status, reason, and confidence. The business must define which evidence authorizes inventory release, service activation, withdrawal, refund, and revenue recognition.
Creating a dynamic charge or payment resource records an instruction opportunity, not money movement. Customer authorization confirms intent under a specific consent and context. Settlement is the movement completed by the payment infrastructure. Funds availability and merchant posting may be observed through provider APIs, account statements, or ledger files.
A PSP webhook is valuable for low latency but remains one evidence channel. Authenticate it, store it immutably, then verify critical outcomes against an authoritative status endpoint or account transaction feed. A missing webhook must not permanently hide a settled payment; a forged or duplicated webhook must not release value.
Network timeouts can occur after a PSP accepts a request. Retrying with a new business identifier may create another charge or payment. Generate the idempotency key before the first attempt, bind it to merchant, operation type, amount, destination, and payload hash, then retain the original response and state.
Inbound events also require deduplication. Use provider event ID where available, but enforce uniqueness on durable payment facts such as provider, txid, end-to-end ID, event type, and version. A repeated settlement notification should return the existing journal entry and order transition.
A mutable payment row is useful for the latest projection. It is insufficient for financial integrity. Use an append-only double-entry ledger where each journal balances and references the source event. Separate receivable, clearing, available cash, customer balance, merchant payable, fee, refund liability, loss, and suspense accounts according to the product.
Never edit historical money entries to “fix” a value. Post reversal or adjustment journals with explicit reason and authorization. Rebuild projections from entries and test invariants: debits equal credits, currency is consistent, no account violates its rules, and every business release points to a committed journal.
Operational reconciliation compares the webhook inbox with provider API status. Cash reconciliation compares provider or bank transactions with the internal cash/clearing ledger. Business reconciliation compares paid receivables with orders, invoices, subscriptions, or payouts. Accounting reconciliation compares ledger balances and journal exports with the general ledger.
These runs have different frequencies and tolerances. Near-real-time checks catch a paid order stuck in pending. Intraday cash matching detects missing or duplicate postings. Daily close detects fees, returns, timing boundaries, and files that failed after the operational system already succeeded.
First match exact identifiers: end-to-end ID, txid, payment ID, provider transaction, account, amount, and currency. Then use constrained secondary keys such as settlement window, payer/receiver, invoice reference, and known provider transformations. Never auto-apply a fuzzy match that can move money or close an invoice without a bounded confidence policy.
Unmatched funds belong in suspense with an owner and aging policy. Partial or aggregate settlements need explicit allocation rules. Store why a match occurred, which fields agreed, which differed, and whether a human approved it.
| Discrepancy | Likely cause | Automated check | Safe action | Escalation evidence |
|---|---|---|---|---|
| Provider settled; order pending | Lost webhook, worker failure, lock conflict, schema/version error. | Query authoritative payment, locate ledger and order transition by identifiers. | Post/apply idempotently if evidence and invariants pass. | Raw event, API response, journal, worker trace, order version. |
| Order marked paid; no cash evidence | Forged event, premature status mapping, test/prod mix, manual override. | Check provider, statement, receiver, amount, credentials, and environment. | Freeze release or payout; open high-priority investigation. | Actor, rule, source payload, account statement, authorization trail. |
| Duplicate payment | Retry with new key, customer paid two charges, provider replay. | Group by order, amount, payer, time, txid/end-to-end IDs. | Do not merge silently; apply refund or credit policy with approval. | Both transaction proofs, customer intent, refund eligibility. |
| Amount mismatch | Stale charge, discount change, fee netting, partial payment, wrong invoice. | Compare gross, net, fees, expected amount, currency, and quote version. | Route to suspense or partial-allocation policy. | Charge, invoice, fee schedule, statement and policy version. |
| Return/refund mismatch | Return pending, partial return, wrong original transaction, duplicate refund. | Link original payment, return ID, amount, status, journal, and customer case. | Post only verified return states; preserve pending liability. | Original and return evidence, reason, authorization, ledger lines. |
| Consent authorized; payment absent | User journey stopped, payment rejected, expired consent, participant failure. | Read consent and payment resources independently and inspect reason codes. | Show accurate status; offer a new journey without reusing invalid authority. | Consent/payment IDs, timestamps, client, participant and status history. |
A merchant refund is a business decision linked to an original payment and customer obligation. A Pix return follows the payment rail's return mechanisms and identifiers. The Special Return Mechanism addresses specific fraud scenarios and does not replace ordinary customer-service refunds or fraud prevention.
Model requested, approved, submitted, processing, completed, rejected, canceled, partial, and failed. Reserve a refund liability when the business commits, but mark cash returned only from verified rail evidence. Prevent total returns from exceeding the original eligible amount.
Payment initiation involves consent, authorization, client identity, participant, resource status, and potentially redirect or decoupled journeys. Preserve the complete state history. A payment must not outlive the scope, amount, creditor, schedule, or validity that the customer authorized.
Use financial-grade API controls: strong client authentication, sender-constrained access where specified, exact validation, short-lived authority, key rotation, signed requests and responses where required, replay prevention, and conformance testing. Keep API version and participant behavior in every trace because ecosystem migrations can create asymmetric failures.
Before initiation, evaluate account tenure, device and session change, beneficiary history, value, velocity, time, location, channel, behavior, scam indicators, and policy limits. During authorization, preserve what the customer saw and approved. After settlement, monitor linked accounts, return patterns, disputes, mule indicators, and recovery outcomes.
Risk models should return reason codes and calibrated decisions, not an unexplained score. Measure prevented loss together with false positives, abandonment, accessibility, manual-review time, customer complaints, and recovery.
Trace every payment across order, consent, charge, payment resource, webhook, provider query, end-to-end ID, bank entry, ledger journal, business transition, refund, and exception case. Metrics include event lag, dedupe rate, status-transition latency, unmatched value, suspense age, ledger imbalance attempts, reconciliation completion, exception backlog, and time to resolution.
Alert on value and age, not only error counts. Ten low-value unmatched entries and one high-value order released without cash evidence are not equivalent. Dashboards should distinguish expected timing gaps from broken invariants.
Replay timeouts after acceptance, duplicate requests, webhook loss and reordering, participant downtime, late settlement, API/statement disagreement, day-boundary timestamps, partial returns, duplicate refunds, malformed identifiers, currency precision, key rotation, consent expiration, and processing resumed after deployment.
Run a simulated daily close. Freeze an accounting window, ingest late entries under policy, reconcile balances, produce exception reports, export journals, and prove that rerunning the same close does not duplicate entries.
I would build a payment control plane with provider adapters, durable request outbox, immutable webhook inbox, consent and payment state machines, risk gateway, status verifier, double-entry ledger, business transition service, reconciliation engine, suspense queue, exception console, and accounting exports.
Every adapter would map external status to a versioned internal vocabulary without discarding the original code. The reconciliation engine would operate from independent evidence, and every automatic correction would be idempotent, explainable, and reversible through a new journal.
Fast settlement does not remove accounting complexity; it compresses the time available to handle it. Reliable Pix and Open Finance systems separate states, preserve identifiers, post immutable balanced entries, verify independent evidence, and treat every mismatch as owned operational work.
Article about Pix and Open Finance reconciliation pipelines in Brazil, including payment state machines, consent, idempotency, settlement evidence, double-entry ledgers, matching, refunds, MED, fraud controls, exception handling, testing, and observability.