ParsePesa
System Architecture

Financial Event Reconciliation

Payment processing in African networks is frequently tangled and out-of-order. A customer might receive a transaction SMS alert before the payment processor callbacks complete, or vice-versa. Duplicate callback loops (retry storms) are common.

ParsePesa utilizes a high-performance, transaction-aware Reconciliation Engine that automatically deduplicates incoming events, prevents double-billing, and merges records across SMS and IPN channels under a single Payment Intent lifecycle.

Three-Level Deduplication

For every incoming callback, the reconciliation layer applies the following validations within a transaction boundary:

1. Unique Event ID LookupWe check the database for any raw events already logged with the identical `provider_event_id` (e.g. Flutterwave event ID or Paystack event key). If found, it is immediately discarded.
2. Reference & Status UniquenessWe query the provider logs for a matching combination of `provider_reference` and `raw_status` in the same tenant workspace. This filters out exact state duplicate callbacks.
3. Ten-Minute Token Storm WindowIf a provider enters a loop and sends identical metadata (same Merchant Order ID and same status) within a 10-minute sliding window, the engine blocks the storm, returning HTTP 200 to silence provider retry loops.

State Machine Transitions

To prevent terminal degradation (e.g. a delayed "pending" callback overwriting a previously resolved "succeeded" state), the engine validates all state updates:

  • Forward Paths: `initiated` → `pending` → `succeeded` or `failed`.
  • Terminal Locks: Once a transaction transitions to `succeeded`, it can only transition to `reversed`, `refunded`, or `settled`. Any inbound event attempting to change it back to `failed` or `pending` is rejected as a stale callback.
  • Bypass: Ignored stale callbacks still return HTTP 200 to the provider but do not bill the customer or queue outbound webhooks.
← Custom Webhook MappingEvent Replay & Dead-Letter →