Forex payment gateway integration: flows and reconciliation.
Payments are asynchronous and failure-prone. Design the states, the callbacks and the reconciliation before connecting anything.
State model
Define states for deposits and withdrawals: initiated, pending, approved, completed, failed, reversed. Specify allowed transitions and who or what triggers them, including manual review.
Callbacks and idempotency
Providers notify by callback. Verify signatures, handle duplicates and out-of-order messages, and make crediting idempotent so repeated notices never double-credit.
Reconciliation
Run daily jobs that match provider reports to CRM records and platform balances, with an exceptions queue. Link provider selection to the PSP notes.
Logging and traceability
Assign a correlation identifier to each transaction and log it across gateway, CRM and platform. Traceability turns a disputed payment from a search into a lookup, and helps reconciliation and audits.
Failure scenarios to test
Callback delayed, callback duplicated, callback out of order, provider timeout, amount mismatch and reversal after credit. Define the expected behaviour for each and test them. Failure behaviour defines the quality of an integration.
Questions we hear
Where does manual review fit?
As explicit states with approvers, thresholds and audit records.
How are chargebacks represented?
As a reversal state linked to the original transaction.