Design a secure payment reconciliation workflow

A customer’s order, a provider’s payment attempt and a bank settlement are related records, but they are not the same event. Model them separately. A reliable reconciliation process explains both the expected outcome and the exceptions without erasing the original evidence.

Keep the identifiers separate

Give the order its own identity and each payment attempt another. Store the provider reference alongside the attempt rather than replacing your order number with it. A retried checkout can create another attempt against the same order.

Define the money unit and expected amount before contacting the provider. Where a provider uses a smaller unit such as paisa, keep the conversion explicit. Avoid floating-point arithmetic for stored monetary amounts; choose an exact representation suitable for your system.

Make one fulfilment decision

Treat a browser return as input to verification, not proof of payment. Match the provider’s authoritative result to the stored order, attempt and merchant context. Keep unknown states pending or under review rather than mapping every non-error response to paid.

Use an atomic state change and a database uniqueness rule for the fulfilment event. Replaying the same verified result should leave the order in the same correct state, without shipping again or creating another credit. This is a design requirement to test, not a claim that a diagram makes the implementation safe.

Reconcile the bank movement later

Compare payment evidence with provider reports and bank entries. Preserve the gross payment, applicable fees, refunds and net settlement separately. Do not force a payout that covers several orders into one order’s payment amount.

Maintain an exception queue with an owner and a reason: missing bank reference, amount mismatch, reversed transaction or unmatched refund. Keep investigation notes and corrections as additional records.

Test the difficult cases

Include duplicate callbacks, a return before a lookup completes, delayed settlement, wrong amounts, partial refunds and a provider timeout. Check that each case preserves evidence and avoids duplicate fulfilment.

Build a provider adapter from the documentation approved for your account. The Nepal gateway guide links the current primary starting points and explains why notification formats and settlement terms should not be generalised.

Read the provider-specific Nepal payment guide →