Payment gateway and API integrations look small on a project plan and cause a large share of the problems. Payments that succeed but are never recorded, orders marked paid that never were, duplicate charges after a timeout. Almost all of these are prevented by planning. Use this checklist before you integrate a payment gateway or any third-party API.

Before you choose a gateway

  • Countries and currencies. Does it support your business's country and your customers' cards, wallets and banks?
  • Fees and payouts. Transaction fees, currency conversion, payout schedule and minimums.
  • Features you need. Subscriptions, refunds, partial refunds, saved cards, invoices.
  • Documentation and a sandbox. Clear API docs and a test environment are signs of a gateway that is easy to integrate.

Never trust the browser redirect

This is the most important rule. When a customer returns from the payment page to your "success" URL, that redirect proves nothing: it can be bookmarked, replayed or faked. Before you mark an order as paid, your server must verify the transaction directly with the gateway's API, and check that the amount, currency and order reference match what you expected.

Use webhooks, and handle them twice

Customers close the browser before the redirect, and mobile connections drop. Most gateways can also notify your server directly, with a webhook or an IPN. Use it, verify its signature, and design the handler so that receiving the same notification twice changes nothing. The redirect and the webhook will often both arrive, and they must not create two payments.

Make operations idempotent

Network timeouts happen. If your server asks a gateway to charge or refund and the answer never arrives, retrying must not charge twice. Many APIs accept an idempotency key or a unique merchant reference for exactly this. Store it before the call.

Plan for errors and timeouts

  • Set timeouts on every outgoing call, so a slow API cannot freeze your site.
  • Show customers a clear message, and keep the order in a "pending" state that you can resolve.
  • Log the request, the response and the gateway's transaction ID, never full card numbers or secrets.
  • Alert someone when integration errors pass a threshold.

Keep card data out of your systems

Use the gateway's hosted payment page or its tokenization fields, so card numbers never touch your server. That keeps your PCI compliance scope small and your risk low.

Reconcile

Once a day, compare your orders with the gateway's settlement report. Differences show up early, while they are still easy to explain.

For any third-party API

  • Check rate limits and quotas, and what happens when you exceed them.
  • Know how the API is versioned, and subscribe to its change notices.
  • Keep API keys in a secret store, rotate them, and use separate keys for test and live.
  • Wrap the API in one service class, so a future provider change touches one place.

We have integrated payment gateways, including local gateways in Bangladesh, SMS providers and business APIs into our own products and client systems. See our API and payment integration service, or tell us which systems you need to connect.