Insights · 5 min read
Adding payments looks small in the project plan and eats two weeks if you get it wrong. The steps, the methods, and the mistakes that cost teams the most.
By GGP Editorial
Adding payments to your app or website looks small in the project plan and then eats two weeks if you get it wrong. It is the kind of feature where the happy path is easy and the edge cases are where the money leaks. This is a plain-language walkthrough of what the job actually involves.
Payment gateway integration means connecting your checkout to a processor so money moves from your customer to you. The hard part is not the first successful test payment. It is everything around it: refunds, failed charges, currencies, webhooks, and the local payment methods your customers already expect.
Do not pick the cheapest. Pick the one that supports the markets and payment methods you actually sell into. A gateway that works in the US can fall flat in Brazil, where Pix is the default, or in Singapore, where PayNow matters. Payment habits are local, and your conversion rate follows them.
| Gateway type | Examples | Best for |
|---|---|---|
| Global aggregator | Stripe, Adyen, PayPal | Startups, multi-market reach |
| Local payment provider | A Brazilian PSP with Pix, a South African provider | One market, deep local methods |
| Direct merchant account | Your bank's acquiring service | High volume, lower per-transaction fees |
If you sell across borders, choose a gateway that already supports the local methods your customers use. Adding Pix or local card schemes later is a second project, not a setting you switch on.
There are three ways to build, and they trade control against effort and compliance burden.
| Method | Effort | PCI burden | Control over checkout |
|---|---|---|---|
| Hosted or redirect checkout | Low | Low | Low |
| Drop-in or embedded form | Medium | Medium | Medium |
| Direct API | High | High | High |
Hosted checkout sends the customer to the gateway's own page. It is the fastest to launch and keeps most card data off your servers, which shrinks your PCI scope. A drop-in form keeps the customer on your site with the gateway's UI embedded. A direct API gives you full control of the checkout and the most PCI responsibility, so only go there if you have a real reason, such as a custom design or unusual business logic.
A few technical decisions separate a solid integration from a fragile one.
Create a payment intent or order before you show the checkout, and carry an idempotency key on every charge. That key is what stops a double-click or a retried request from charging the customer twice. It is a small addition and one of the most common omissions.
Decide whether you authorize then capture, or capture immediately. Authorize-then-capture lets you hold the money and charge only when you ship or confirm, which matters for anything with a fulfillment step.
Handle 3D Secure and Strong Customer Authentication. In Europe SCA is mandatory, and even outside Europe more banks require it. If your gateway offers a route that avoids the challenge when it can, use it, but build for the case where it is triggered anyway.
Treat webhooks as the source of truth, not the redirect. The customer may close the browser after paying and never return to your thank-you page. The webhook is the only reliable signal that the money actually moved, so make it idempotent and retry on failure.
Trusting the redirect URL as proof of payment instead of the webhook is the classic one. It works in testing and fails in production when a real customer closes a tab.
Hardcoding sandbox keys and shipping them to production is another. It happens more than anyone admits, and the fix is simple: keep keys in configuration, never in code, and rotate them when a developer leaves.
Skipping idempotency means retried payments can charge twice, and a double charge is an expensive support ticket. Forgetting refunds and partial refunds until the first customer asks for one is how a small feature turns into a compliance problem.
Ignoring local payment methods in a new market quietly kills conversion. And storing raw card numbers instead of tokens turns a small feature into a PCI audit you did not plan for.
Reconciliation is the quiet one. Your gateway report and your order system must line up to the cent, and someone needs to check that daily or weekly, or you find the gaps in an audit instead of in your dashboard.
A single gateway rarely covers everywhere well. We have built payment integrations for clients in Brazil, South Africa, Singapore, and the US, and the pattern repeats: local methods drive conversion where cards do not, and each market adds its own compliance notes. The approach that holds up is to pick the gateway for the market, then wrap the differences behind one payment layer in your own system.
Get the gateway, the method, and the webhook flow right and payments stop being the feature everyone is afraid to touch.
Tell us what you are building and where you are today. We typically reply within 24 hours.
