Payment gateway integration: what to handle besides taking cards
Accepting cards can be wired up in a day: providers ship libraries and clear documentation. The problems start afterwards — when a payment succeeds but the notification never arrives, when a user clicks pay twice, when money is taken and the order is never created. Those scenarios are the actual work.
What the integration covers besides payment
A full integration handles the whole payment lifecycle:
- Creating a payment and redirecting the user.
- Receiving status notifications from the provider.
- Reconciliation: comparing your records against the provider's settlement.
- Refunds, full and partial.
- Recurring charges for subscriptions and handling failed attempts.
- Disputes and chargebacks — supplying evidence when the bank asks.
- Reporting for accounting and receipts.
Reconciliation is the item most often left out of a project, and without it discrepancies between your database and the money in the account surface months later and get resolved by hand.
Webhooks: the main source of bugs
The provider notifies you of a status change by webhook — a request to your endpoint. Three rules around them get broken most often.
A notification can arrive twice. Networks are unreliable, the provider retries, and your handler receives the same message several times. If it fulfils an order on every call, you ship three times.
A notification can arrive out of order. A success message sometimes lands after a refund message. Statuses must be processed against current state rather than blindly.
A notification may never arrive. So payment status cannot be treated as final based on webhooks alone: you need periodic reconciliation through the provider's API.
Idempotency in plain terms
The property of an operation producing the same result when repeated. A user clicks twice, the browser retries, the network duplicates a packet — the charge must happen once.
It is implemented with a key: the client sends a unique operation identifier, the server remembers it, and on a repeat with the same key returns the previous result instead of charging again.
Most payment providers support such a key in their API. Always use it — it costs far less than untangling double charges with customers afterwards.
What to weigh when choosing a provider
Not just the fee. Look at:
- Supported payment methods in your countries.
- Payout timelines and holdback terms.
- Documentation quality and whether there is a real sandbox.
- Chargeback policy and who carries the risk.
- Restrictions on business category — some providers exclude whole industries.
- What happens if the provider drops you: can you switch quickly.
That last point is the argument for not binding your logic to one provider's interface from the start, but separating provider handling from the rest of the code.
Security and card data
The simplest rule: do not store card data yourself. If card details touch your server, you fall under PCI DSS requirements, which is a project of its own with audits and ongoing cost.
So most scenarios use the provider's hosted form or embedded fields where data goes straight to them, bypassing your server. You receive only a token.
Separately: provider keys do not belong in the repository, and webhooks must be verified by signature — otherwise anyone can send you a successful-payment notification.
What to test before launch
Walk these scenarios in the sandbox rather than hoping:
- Double-clicking the pay button.
- Closing the tab immediately after paying.
- A webhook delivered twice.
- A webhook never delivered.
- Payment succeeded but order creation failed.
- A partial refund.
- A bank decline at the confirmation step.
Questions people ask
How long does payment gateway integration take?
Basic payment acceptance is quick. Most of the time goes to status handling, reconciliation, refunds and edge cases — which is where the real work lies.
What is a webhook in payments?
A notification from the payment provider about a status change, sent to your endpoint. It can arrive twice, out of order, or not at all, so periodic reconciliation through the API is also required.
What is payment idempotency?
The property of an operation producing one result when repeated. It is implemented with a key: on a repeat request with the same key the provider returns the previous result instead of charging again, which prevents double charges.
Do we need PCI DSS compliance?
If card data never touches your server, requirements are minimal. That is achieved with the provider's hosted form or embedded fields that send data directly to them. Storing cards yourself becomes a separate project with audits.
Can we connect several payment providers?
Yes, and it is sensible: one can drop you or go down. For that, provider handling is separated from the rest of the logic so switching does not require a rewrite.
