Skip to content

Reconciliation

Run Periodic Reconciliation

Why: No distributed system is perfectly reliable. Callbacks can be lost due to network issues, your endpoint may have been down during delivery, or a race condition could cause your local state to diverge from the gateway's state. Reconciliation catches these gaps.

Recommended approach:

  • Run a reconciliation job at least once per day (more frequently for high-volume merchants).
  • For bulk reconciliation, use the Records endpoint to pull every transaction created within a window and diff the whole set against your ledger in one pass.
  • For targeted reconciliation (catching up on stuck transactions), query the Payment Status endpoint for each transaction still in a non-terminal state (pending) in your local database.
  • Compare local status with gateway status and update your records accordingly.
  • Alert on transactions that have been pending for longer than expected (e.g., > 1 hour).
Bulk reconciliation (pseudo-code):

1. window_from = last_reconciled_at; window_to = window_from + 1 hour
2. page = null
3. Loop:
     GET /gateway/mmo/v2/records?from={window_from}&to={window_to}&page={page}
     For each transaction in response.data:
       Upsert into local ledger; flag any divergence
     page = response.pages.next
     Break when page is null
4. Persist window_to as the new checkpoint

Targeted reconciliation (pseudo-code):

1. SELECT * FROM transactions WHERE status = 'pending' AND created_at < now() - interval '30 minutes'
2. For each transaction:
     GET /gateway/mmo/v2/status/{gatewayReference}
     If gateway status is terminal → update local record
     If gateway status is still pending → skip (check again next cycle)
3. Log and alert on any discrepancies

Handle Discrepancies

Why: When your local state differs from the gateway's state, the gateway is the source of truth. Your system should converge to the gateway's state, not the other way around.

Recommended approach:

  • If the gateway says success but your local state is pending: mark as successful and trigger any pending fulfilment.
  • If the gateway says failed but your local state is pending: mark as failed and cancel any pending actions.
  • If you cannot find the transaction on the gateway: investigate whether the original request was ever sent (check your logs for the merchantReference).
  • Log all discrepancies with full context for post-incident review.