Payment gateway integration: a launch checklist.

01 / Confirmation

A checkout return is only one part of the journey.

A customer can finish paying and close the browser before your site opens again. Your backend needs its own route to the outcome. Keep an internal order reference and a separate reference for each payment attempt, then match the provider result to that attempt before taking a business action.

Paystack recommends verifying a transaction before delivering value and checking its amount. Its verification response also separates the API request status from the transaction status. A successful API request alone does not mean the customer paid. Paystack payment verification.

1. 1 Create order
2. 2 Open checkout
3. 3 Verify result
4. 4 Record & fulfil

Give the customer a useful pending state while confirmation is unresolved. A retry should create or reuse the appropriate payment attempt according to the provider's rules; it should not silently create a second order.

02 / Provider differences

Check the contract for each gateway.

A shared integration layer can simplify your application, but notification authentication, event identifiers and retry behaviour belong in provider-specific adapters. Confirm availability for your merchant country and account before choosing a gateway for India, an African market or the UAE.

03 / Processing

Separate receiving an event from fulfilling an order.

For a recoverable design, authenticate the request and store a durable receipt before acknowledging it. Keep the receipt path short enough for the gateway's timeout. Put slower work—inventory updates, invoices, messages and delivery requests—behind that durable record.

Enforce uniqueness in durable storage, not just with a check in application memory. Two workers can receive the same event at the same time. A unique receipt key prevents duplicate inserts, but it does not finish the job: a worker must be able to resume an accepted receipt after a crash.

Track fulfilment separately with a stable business-operation key. If a stock update succeeds and the worker crashes before recording completion, replay must not decrement stock again. Where the downstream system supports idempotency keys, reuse the same key for retries of that operation. Otherwise design a reconciliation or compensating action for ambiguous outcomes.

Keep payment, refund, settlement and fulfilment states separate. A delayed authorisation should not overwrite a later captured state, and a refund should not erase the original payment record. Unknown event types need an explicit handling path rather than an automatic “paid” fallback.

04 / Recovery

Make unresolved payments visible.

Maintain a pending-payment queue with the last status-check time and a named operational owner. Resolve stale attempts through the provider's authenticated status API or reconciliation reports, respecting its limits and account capabilities. Track exceptions that need a person rather than retrying forever.

Run recovery independently of browser redirects. The customer may never revisit the return URL, and the notification may be missing. Reconcile internal payment records with provider records before investigating settlement differences such as fees, refunds or payout timing.

05 / Release checks

Test the failure paths before launch.

Use your provider's supported test environment and keep evidence against each check. The ticks below are a working checklist, not a certification. They stay on this page only and reset when you reload.

• Account & marketConfirm the merchant country, settlement account, currencies and payment methods with the provider.
• CredentialsKeep test and live credentials separate; use a dedicated webhook secret or header where supported.
• Order creationCreate an internal order and payment attempt before checkout; calculate the amount on the server.
• Payment matchingMatch the verified merchant or outlet, order reference, amount and currency to the intended attempt.
• Invalid notificationSend a forged notification or invalid signature; confirm it cannot mark an order paid.
• Closed browserClose checkout before the return redirect; confirm the backend still resolves the payment.
• Duplicate deliveryDeliver the same event twice, including concurrently; confirm one business action.
• Event orderDeliver an earlier state after a later state; confirm payment status does not move backwards.
• Storage failureInterrupt durable storage before acknowledgement; verify the provider-specific recovery path.
• Worker restartStop processing after receipt is stored; restart it and confirm the event can be completed.
• Fulfilment retryRetry fulfilment after a timeout; confirm stock, email and delivery actions are not duplicated.
• Missing callbackSuppress a callback; resolve the pending payment through an authenticated status query or report.
• Refund lifecycleCheck a partial refund and a full refund separately from payment, fulfilment and settlement.
• MismatchSend a valid event for the wrong amount, currency or merchant; keep it out of fulfilment and flag it.
• Unknown eventAdd an unknown event type or JSON field; preserve compatibility without treating it as success.
• Release handoverRecord pending-payment alerts, reconciliation ownership, rollback steps and sanitized test evidence.

06 / Handover

Make the integration operable after release.

Hand over the event mapping, order-state rules, credential owner, alert thresholds and the procedure for resolving a stuck payment. Include the test evidence and a clear rollback boundary. A release is easier to support when the next engineer can trace one order from checkout to fulfilment.

Need these payment records connected to invoicing or commerce operations? See our accounting integration services and marketplace integration services.