A payment integration that works in the sandbox is not the same as one that works in production. The difference is everything that goes wrong: slow responses, abandoned authentication, duplicate requests, missed notifications and customers who close the tab at the worst moment.
This is the checklist we use when we build or review a payment gateway integration. Work through it in order. Each step exists because skipping it creates a problem later.
1. Confirm the requirements
Before any code, write down what the integration must do.
- Which markets and currencies will you serve?
- Which payment methods do customers expect?
- What volumes do you expect, and how do they vary through the year?
- What are your refund, cancellation and partial-capture rules?
- Do you need saved cards, subscriptions or one-time payments only?
- Who needs reporting, and in what form?
Answers here decide almost every later choice. A subscription business and a one-off checkout need different designs.
2. Choose hosted pages or a direct API
Hosted payment pages send the customer to a page run by the provider, or embed one. They launch faster, and the provider handles more of the sensitive data. Direct API integrations let you build the exact experience you want, with more responsibility for security and for the logic around it.
The choice affects your compliance scope, your design freedom and your maintenance burden. For many teams, a hosted or embedded approach is the right start. If you need full control of the flow, plan the extra work.
3. Design the payment states
Draw the states a payment can be in before you write code. A simple model has these:
| State | Meaning |
|---|---|
| Created | You have asked the provider to start a payment |
| Pending | The outcome is not known yet |
| Authorized | The provider approved it, but funds are not captured |
| Captured | The funds are taken |
| Failed | It was declined or errored |
| Refunded | Funds were returned, in full or in part |
The pending state is the one most integrations forget. Decide what your system does when a payment sits in it, how long it waits and what resolves it. We cover this in detail in our article on payments stuck in pending.
4. Keep the logic on the server
The browser tells you what the customer did. It cannot be trusted as proof of payment. Always confirm the outcome server to server before you fulfill an order, release a digital product or mark an invoice as paid.
Keep secret keys on the server, never in front-end code or mobile apps.
5. Build authentication properly
For card payments, authentication such as 3DS2 can interrupt the flow. Plan for each outcome: the customer passes, fails, abandons or hits a timeout. Test across browsers and devices, because authentication behaves differently on each.
We cover where these integrations break in 3DS2 for MENA merchants.
6. Make webhooks reliable
Webhooks are how the provider tells you what happened. Treat them carefully.
- Verify the signature on every notification, so you know it came from the provider.
- Respond quickly and do heavy work afterward, so the provider does not retry unnecessarily.
- Handle duplicates. Providers can send the same event more than once, so processing must be safe to repeat.
- Do not assume order. Events can arrive out of sequence, so use the payment's current state, not only the latest message.
- Log everything, with the payment identifier, so you can trace what happened.
7. Use idempotency
Network calls fail in ways that leave you unsure whether they worked. If you retry a charge without protection, the customer might be charged twice.
Idempotency keys solve this. Generate a unique value for each payment attempt and send it with the request. If you retry, the provider sees the same key and returns the original result.
8. Design retries and fallbacks
Decide in advance what happens when things fail.
- When a request times out, check the payment's status before you try again.
- When the provider is down, show a clear message and keep the order recoverable.
- When a retry is allowed, limit how often and how fast, and never retry declines that should not be retried.
- When authentication fails, give the customer a clear way to try another method.
9. Handle refunds, voids and partial captures
Refunds are part of the product, not an afterthought. Build them for full and partial amounts, and make sure each one updates your own records. Decide how you handle failed refunds and how long customers wait.
If you authorize first and capture later, handle expiries and partial captures too.
10. Plan reconciliation and reporting
Your finance team must be able to match each payment to an order and to a settlement line. Store the provider's identifiers with every payment, keep a record of fees and currency, and run a regular check that finds payments your system and the provider disagree about.
11. Test beyond the happy path
A useful test plan covers:
- Successful payments for every method
- Declines of different kinds
- Failed and abandoned authentication
- Timeouts and slow responses
- Duplicate requests and duplicate webhooks
- Refunds and partial refunds
- A page closed halfway through payment
- Mobile devices and several browsers
Use the sandbox's ability to simulate failure. If it cannot, build your own test doubles.
12. Go live in a controlled way
A careful launch limits the damage if something is wrong. Start with a small share of traffic or a limited audience, watch the results closely and expand once you are confident.
After go-live, review real decline reasons, pending payments and webhook failures. The first live week usually shows issues that testing did not.
13. Monitor continuously
Set up dashboards and alerts for approval rates by method, payments stuck in pending, webhook failures and refund errors. A drop in any of them is an early warning, and you want to see it before customers write in.
Security basics that belong in every integration
Payment code handles sensitive data, so a few habits are non-negotiable.
- Keep secrets out of source code, logs and error messages.
- Avoid handling raw card data where a hosted page or a token can do the job.
- Restrict who can issue refunds and who can see payment details, and log every such action.
- Rotate keys on a schedule, and have a plan for the day one is exposed.
- Review your compliance obligations with your provider. They depend on how you integrate.
What a good handover looks like
An integration is only finished when someone else can run it. Before you close the project, make sure you have written down how payments flow through your system, where each key lives, how to replay a webhook, how to reconcile a day's payments and who to call at the provider. The person who inherits it in a year will be grateful.
Where to go next
If you would like a team to build or review your integration, see our payment gateway integration service. If your integration is live and performing below expectations, our approval-rate optimization service looks at where payments are being lost.
