An electronic payment integration is a distributed state machine, not a button and a success page. The application creates or identifies an obligation, the provider processes one or more attempts, notifications can arrive late or more than once, and settlement or refund may happen later. Reliable design separates the invoice or order from attempts and provider events, verifies outcomes on the server, and gives finance and support a reconciliation trail. Provider capabilities and fees vary, so confirm current documentation instead of embedding assumptions.
Model the business obligation first
Define what is being paid, who owes it, the currency, amount, expiry, and allowed partial or overpayment behavior. Give the invoice or order a stable internal identifier. Decide when it becomes payable and what cancellation means. Do not let a provider response become the only record of the business transaction. The e-invoicing readiness guide covers document flow, while the notification automation guide explains how downstream confirmations should follow events.
Separate attempts from the invoice
One invoice may have a failed attempt, an abandoned attempt, and a later successful attempt. Store each with its internal ID, provider reference, requested amount and currency, state, timestamps, and safe response metadata. The invoice derives its payment state from accepted events and business rules. Never overwrite the first attempt with the latest. This separation also supports partial refunds, charge review, and a clear support conversation.
Define states from provider capabilities
Use states such as created, pending, authorized, paid, failed, cancelled, expired, partially refunded, and refunded only when they match the selected rail. Document allowed transitions. The browser return can improve user experience but must not authorize the state. Avoid a generic success boolean that loses whether funds are pending or final. Map provider codes to internal reasons without discarding the original safe reference.
Verify notifications on the server
Validate signatures or use the provider’s documented server verification mechanism. Check event type, account context, amount, currency, and references before applying a transition. Fetch current status when documentation requires it. Reject malformed or mismatched callbacks and log a correlation reference without secrets. Keep credentials in protected server configuration, rotate them, and separate test from production. The client must never hold a credential capable of confirming its own payment.
Make event handling idempotent
Providers retry notifications, networks duplicate requests, and queues can redeliver jobs. Store a provider event ID or a derived unique key and process it inside a transaction. If the event was handled, return the expected acknowledgement without repeating side effects. Protect the business transition as well as the event insert. Email, stock updates, and invoice status must not run twice merely because a callback arrived twice.
Handle uncertainty explicitly
A timeout while creating an attempt does not prove failure. Record the request identity, query provider status where possible, and show “checking payment” rather than inviting uncontrolled retries. If a user starts another attempt, keep both and define how a later success is resolved. Create a support queue for unknown or mismatched states. Do not auto-refund or mark paid from guesswork; financial exceptions need controlled actions and an audit trail.
Design refunds as transactions
A refund has its own amount, reason, authorization, provider reference, state, and events. Validate that cumulative refunds do not exceed the captured amount under the applicable rules. Require stronger permission or approval where appropriate. The customer-facing message should reflect requested versus completed, not promise money has arrived before provider confirmation. Reconcile refunds separately and preserve the original payment record.
Build daily reconciliation
Compare provider reports or APIs with internal successful attempts, invoices, refunds, and settlement where available. Surface missing provider events, internal paid states with no provider match, amount differences, duplicates, and aged pending items. Assign each exception to finance, support, or engineering. A dashboard total is not reconciliation if no one can trace a line to an invoice and provider reference. Retain evidence according to policy.
Keep providers behind an adapter
Define internal operations and normalized events, then implement provider-specific mapping at the edge. Do not pretend all providers support authorization, partial capture, refund, or webhook delivery identically. Preserve provider-specific details needed for support without leaking them through every business module. Contract-test adapters with documented fixtures and sandbox behavior, and plan a controlled certification or production verification where required.
Test adversarial sequences
Cover duplicate callbacks, out-of-order events, wrong amount, wrong currency, expired attempt, delayed success, client close before return, provider outage, queue retry, partial refund, and manual review. Use provider test tools and your own fixtures. Verify authorization on support actions. Load-test callback handling without logging payload secrets. Monitor event lag, reconciliation exceptions, and error categories after release, then review against current provider documentation.
Conclusion: make every money state explainable
The integration is ready when support can trace an invoice through attempts, verified events, settlement, and refunds without changing data by intuition. Start with the state model and reconciliation before polishing checkout. For a provider-specific design review, request an electronic payment integration assessment with documentation, sample events, refund rules, and the finance team’s reconciliation process.