Blog
Payment gateway integration: a practical guide.
Pick the provider that fits how you collect money, keep card data off your servers, trust the webhooks, plan for disputes, and design a checkout people finish.
Payment gateway integration is the work of connecting your software to a service that securely authorises and moves money between your customer, their bank and your account. Done well, it is mostly configuration and a few API calls; done badly, it exposes you to fraud, failed charges and compliance risk.
This guide walks through the decisions that matter when you add payments to a web application, from picking a provider to designing a checkout people actually finish. A gateway sits between your application and the card networks. When a customer pays, your software sends the transaction to the gateway, which routes it to the processor and the customer's bank for authorisation and returns an approval or a decline. You never want raw card numbers flowing through or resting on your own servers, and that one idea shapes almost every choice below.
Choosing the right payment provider
Match the provider to how your business actually collects money. A provider that excels at one-off online checkout may be a poor fit for a hotel system that takes deposits, incidentals and group folios, or a school platform collecting fees in instalments. The choice drives your fees, the payment methods you can offer, how fast money settles and how much compliance work lands on you. Weigh:
- Payment methods and regions. The cards, wallets and local methods your customers use, in every country you serve.
- Pricing. Percentage and fixed fees per transaction, monthly minimums, and charges for refunds and disputes.
- Developer experience. Clear documentation, a sandbox and stable libraries save weeks.
- Payout schedule. How quickly settled funds reach your bank, since cash flow depends on it.
- Compliance support. Tokenisation and hosted card fields, so card data never touches your systems.
Keep the provider behind a clean internal interface rather than wiring its API calls through your business logic. Then switching provider, or adding a second one for another country, is a contained change rather than a rewrite.
Handling cards, wallets and recurring billing
Accept more than card numbers typed into a form. Many customers now expect wallets such as Apple Pay and Google Pay at checkout, and in Baymard's research 9% of shoppers who abandoned a purchase did so partly because there were not enough payment methods. The practical goal is to support cards, wallets and subscriptions through one provider, so you maintain one integration and one reconciliation process.
For cards, collect the details through the provider's tokenisation element. The provider returns a token, a safe stand-in for the card, and your software stores and charges that token. Wallets work the same way: the device returns an encrypted credential that you pass to the gateway, so your code never sees the card number.
Recurring billing follows the same rule. Store the provider's token, not the card, and let its subscription features handle the tedious parts:
- Scheduled charges, and proration when a plan changes mid-cycle.
- Automatic retries and reminder emails when a charge fails.
- Webhooks that tell your system when a payment succeeded or failed, or a card is about to expire.
Treat those webhooks as the source of truth. Timeouts and customers closing the tab mean the checkout response alone cannot tell you a payment's final state, so mark an order or invoice paid only when the provider confirms it.
Security and PCI compliance
Any system that stores, processes or transmits cardholder data must meet the Payment Card Industry Data Security Standard (PCI DSS). The current version is 4.0.1, published with its supporting documents by the PCI Security Standards Council and built around twelve core requirements. The most effective way to simplify compliance is to design so that raw card data never reaches your servers at all.
The stakes are high. IBM and the Ponemon Institute put the global average cost of a data breach at USD 4.99 million in the 2026 Cost of a Data Breach Report, up 12% on the year before and a record. Payment data is a prime target, so holding less of it cuts both your risk and your audit scope. Three practices do most of the work:
- Tokenisation. Replace card numbers with provider tokens, so a breach of your database yields nothing a thief can spend.
- Hosted or embedded fields. Let the provider's page, frame or library capture card details, keeping them out of your application entirely.
- Transport security. Serve everything over current TLS, and never log full card numbers, security codes or authentication data.
When card capture is fully handed to the provider, many smaller online merchants can validate with the shortest self-assessment questionnaire instead of a full on-site assessment. Which validation applies is set by your acquiring bank and the card brands, mostly by transaction volume, so ask before you design around it. It is still a strong reason to use the provider's hosted components even when a fully custom form is tempting.
Managing refunds and disputes
Refunds and disputes are part of normal operations, so build for them before launch. A refund is a transaction you start to return funds. A dispute, or chargeback, is started by the customer's bank and can carry extra fees and a response deadline.
Store the provider's transaction ID and a clear reference to the order with every payment. That link lets staff issue a full or partial refund quickly and gives you the evidence trail if a charge is disputed. Listen for the provider's dispute webhooks too, so your system learns about a chargeback the day the bank raises it, not days later when the deadline is close. The evidence a provider asks for is usually the order record, proof of delivery or service, and your refund policy; keeping those attached to each transaction turns a dispute from a scramble into a routine task.
Designing a checkout people finish
Checkout is where integration quality becomes revenue. The Baymard Institute, averaging 50 studies, puts online cart abandonment at 70.22%. Leaving aside people who were only browsing, US shoppers in its research most often gave these reasons: extra costs such as shipping, tax and fees (40%), not trusting the site with their card (19%), being made to create an account (18%), a long or complicated checkout (17%), and a declined card (10%). Most of those are design problems with design fixes:
- Offer guest checkout. Do not make an account a condition of paying.
- Show the total early. Surface taxes and fees before the final step so the number never jumps.
- Ask for less. Request only what the payment needs, and use autofill where the device supports it.
- Put wallets first. A one-tap wallet button skips card entry for mobile buyers.
- Handle declines kindly. Keep what was entered, explain what happened and let the customer try again in place.
Test the unhappy paths as thoroughly as the happy one: declines, timeouts, expired cards and double submissions, because that is where most checkout failures come from.
Where our own systems stand
Plainly: none of our eight systems takes card payments online today. Each one records payments, whether cash, card at the desk or bank transfer, against the invoice or booking they settle, and on each one's Integrations page, payment gateways are marked "coming soon". If online card payment is essential to you from day one, ask us where that work stands before you choose, and ask any other vendor the same question: which gateways are live today, not on the roadmap. When we build it, it will follow the rules above: hosted card fields, tokens instead of card numbers, and nothing marked paid until the provider confirms it.
Questions about payment gateway integration
What is payment gateway integration?
Connecting your software to a service that authorises and processes electronic payments. It passes card or wallet data securely to the processor and banks, then returns an approval or decline to your application.
Do I need to be PCI compliant to accept payments?
Yes. Anyone accepting card payments must meet PCI DSS. Using a provider's hosted fields or tokenisation keeps card data off your systems, which shrinks what you have to secure and usually simplifies how you validate compliance.
Should I use a hosted checkout or an embedded payment form?
A hosted checkout is the fastest path with the least compliance work. Embedded, provider-hosted fields give you more control over the design while still keeping raw card data off your servers.
How do I handle recurring billing?
Store a payment token from the provider rather than the card number, then charge the token on a schedule. Most gateways offer subscription features that handle billing cycles, retries for failed charges and proration.
Pick one provider that covers the payment methods you need and offers tokenisation, then build a small sandbox integration that runs a single payment end to end, including a webhook that updates your own records. That narrow slice teaches you more about the provider's quirks than any amount of documentation. For the wider picture, see why API-first architecture matters, or ask us what payments look like in the system you are considering.