Choose a system of record before choosing more rails
A payment operation becomes easier to run when every team knows which record answers which question.
Draw one path from checkout to your order database, payment provider, ledger, settlement report, and support console. For each handoff, write down the identifier created, the status returned, and the system allowed to change that status. This exposes gaps before they become production mysteries.
The order system should own fulfillment intent, while the payment system owns the verified payment state. Do not infer one from the other. A customer can leave the browser before a payment completes, and a successful authorization can still precede a failed capture or an unfulfilled order.
- Create the order reference before the first payment attempt.
- Store every payment attempt separately, including abandoned and failed attempts.
- Link captures, refunds, disputes, fees, and settlement entries to the original attempt.
- Name the source of truth for customer messaging, fulfillment, and finance reporting.
Turn provider responses into a shared status contract
Provider-specific codes are useful evidence, but they should not become your product language. Define a small set of internal states such as created, action required, authorized, captured, failed, canceled, refunded, disputed, and settled. Document the exact conditions for entering and leaving each state.
For every non-final state, record who or what can advance it, how long the operation may wait, and what the customer should see. A redirect timeout, for example, should remain pending until a webhook or status lookup confirms the result; it should not immediately invite another payment.
- Mark states as final or recoverable so retry behavior is unambiguous.
- Store the raw provider code beside the normalized state for investigation.
- Attach a plain-language reason and next action for support.
- Version the mapping so historical transactions remain explainable after provider changes.
Make retries safe before adding recovery prompts
Generate an idempotency key on your server for each intended operation and reuse it when the same request is repeated. A new click is not automatically a new intent: double taps, network retries, browser refreshes, and worker restarts can all replay the original action.
When the outcome is unknown, query the provider or wait for the asynchronous event before creating a replacement attempt. If the customer truly starts over, create a new attempt linked to the same order so operators can see the complete sequence.
- Disable duplicate submission in the interface, but never rely on the interface alone.
- Persist the idempotency key before calling an external service.
- Verify webhook signatures and ignore duplicate event IDs.
- Alert on an order with multiple successful captures, even if prevention controls exist.
Reconcile transactions, settlement, and cash every day
Reconciliation is three comparisons, not one. First compare your internal payment records with provider transactions. Then compare provider transactions with settlement batches and fees. Finally compare settlement batches with the cash that reached the bank account.
Create an exception queue instead of silently forcing matches. Each exception should have an amount, currency, expected date, probable cause, owner, and aging clock. Finance should be able to close a period without asking engineering to assemble a fresh export.
- Match on durable IDs first; use amount and date only as supporting evidence.
- Reconcile gross amount, fees, refunds, disputes, reserves, and net settlement separately.
- Track late and missing records as open exceptions rather than deleting them from the report.
- Measure unmatched value and oldest exception, not only the percentage matched.
A green payment dashboard is not proof that the bank balance is correct.
Give support evidence and a controlled next action
Start with the questions customers actually ask: Was I charged? Why is my order pending? When will my refund arrive? Build a safe timeline that answers those questions using verified events, not a single status badge.
For each issue, define the evidence to inspect, the action support may take, the action that requires escalation, and the message to send. Mask payment credentials, restrict refunds and cancellations by role, and keep an audit trail of every operator action.
- Search by order, payment, customer, and provider reference.
- Show timestamps in the operator’s timezone and preserve the original event time.
- Display refund destination and expected timing without revealing sensitive details.
- Require a reason for manual changes and surface whether the action succeeded.
Run a cross-functional go-live review
Before enabling real volume, walk product, engineering, finance, risk, and support through the same scenarios. Use real test records and require each team to find the transaction, explain its state, and identify the next permitted action.
Launch with a named incident owner, dashboards for success rate and latency, reconciliation thresholds, and a rollback condition. Review the first settlement and the first refund—not only the first successful payment—before declaring the integration complete.
- Successful payment, failed payment, authentication challenge, and customer abandonment.
- Timeout followed by late success, duplicate webhook, and repeated submission.
- Full refund, partial refund, dispute, reversal, and settlement fee adjustment.
- Provider degradation, webhook backlog, and an operator action performed with insufficient permission.
