Payment gateway integration guide for small businesses

What does a payment gateway integration actually involve?

A gateway is the service that takes card or Pix details from your customer, talks to the banks, and tells you whether the money moved. You do not become a payment processor by integrating one, and you do not need a license. What you take on is the responsibility for three things on your side of the line.

• Taking the payment. Presenting a checkout, creating the charge or payment intent, and handling the outcomes: approved, declined, pending, expired. Pending is the one that catches people, because a Pix charge or a bank redirect can sit there for minutes or hours.
• Hearing back. The gateway tells you what happened through webhooks, asynchronous HTTP calls to your server. Your order status, your customer's access and your emails all depend on those calls being received, verified, deduplicated and processed in the right order.
• Proving it matches. Every day, the list of payments the gateway says it took has to match the list of orders you marked paid, and the payout that lands in your bank has to match the sum of those minus fees, refunds and disputes. That is reconciliation, and it is where small businesses lose money quietly.

Stripe, Mercado Pago or Pix: which one fits your business?

The three are not competitors in the same market. Stripe is a global gateway with the best documentation in the industry and per-country pricing. Mercado Pago is the dominant gateway in Latin America, with cards, Pix, boleto and wallet balance in one integration. Pix is not a company: it is the instant payment system run by the Central Bank of Brazil, available 24 hours a day, every day, and offered through banks and gateways including both of the above.

Fees are published per country and change; the table uses what each page showed in September 2026 and links to it. Stripe's pricing page for Brazil, for example, lists 3.99 percent plus R$ 0.39 per successful domestic card transaction, with 2 percent more for international cards. The US page lists a different structure. Always read the page for the country where your business is registered.

A common setup for a business selling in Brazil is Mercado Pago or a Brazilian gateway for local methods, Stripe for international customers, and Pix through whichever of them fits, with one internal payment model that does not care which gateway produced the money. That last part is the design decision that makes the rest manageable.

Should you use a hosted checkout or build your own?

Every gateway offers two paths. The hosted checkout (Stripe Checkout, Mercado Pago's Checkout Pro) sends the customer to a page the gateway controls and returns them to you. The API path (Payment Intents on Stripe, the Orders API on Mercado Pago) lets you keep the customer on your own page with the gateway's tokenized fields inside it.

For a small business, hosted checkout is the right default. It keeps card data off your servers, which keeps you in the lightest PCI DSS scope, handles 3D Secure and local methods for you, and gets updated by the gateway when rules change.

Build your own checkout when the flow does not fit a hosted page: a marketplace splitting money between sellers, a subscription that changes mid-cycle, a checkout inside an app, or a conversion rate that justifies removing the redirect. Even then, card fields stay tokenized by the gateway. Raw card numbers never touch your database, in any design, ever.

Why are webhooks the part that breaks?

A webhook is the gateway calling your server to say something happened: a payment succeeded, a Pix expired, a refund completed, a dispute opened. Four things go wrong with them in almost every integration we have been asked to fix.

• The signature is not verified. Stripe signs every event with a Stripe-Signature header that includes a timestamp, and Mercado Pago signs with an x-signature header computed from your secret. If you skip verification, anyone who guesses your endpoint can mark orders as paid.
• The handler is too slow. Gateways expect a fast 2xx response and treat anything else as a failure to retry. The right shape is: verify, store the raw event, answer 200, and process from a queue. Sending the confirmation email inside the webhook handler is how you end up with a timeout and a duplicate.
• Events arrive twice or out of order. Stripe retries deliveries for up to three days with an exponential backoff in live mode. That is a feature, and it means your handler will see the same event more than once. Store the event id, ignore repeats, and never assume the refund event arrives after the payment event just because it was created later.
• Nobody watches the failures. Both dashboards show failed deliveries. Almost nobody looks. A daily check on failed webhooks is a five-minute job that prevents the Monday morning where twenty customers paid and none got access.

Treat the webhook as a hint, not as the truth. When an event arrives, fetch the payment from the gateway's API and update your record from that. It costs one extra call and removes an entire class of bugs.

What is idempotency and why does it save you money?

Idempotency means that doing the same thing twice has the same effect as doing it once. In payments it matters in both directions. Toward the gateway: if your server creates a charge, the connection drops, and you retry, you can charge the customer twice. Stripe solves this with an Idempotency-Key header: send the same key on the retry and Stripe returns the original result instead of creating a second charge. Keys are kept for at least 24 hours, so a retry after that becomes a new request.

Toward your own system: the same webhook processed twice should not grant two months of access or send two receipts. The mechanism is a unique constraint on the event id and on the payment id in your database, so the second insert fails harmlessly and the handler exits.

The money this saves is real. Double charges cost a refund, a support conversation and often the customer. Double credits cost margin you never see. Neither shows up in a demo.

How do you reconcile payments with your database?

Reconciliation is the daily job that compares three lists: what the gateway says it captured, what your database says was paid, and what landed in the bank. Small businesses usually have the first two disagreeing by a few orders a week and never notice until the accountant asks.

• Keep an internal payment record for every attempt, with the gateway, its id, the amount, the currency, the status and the timestamps. Orders link to payments; payments never live inside the order row.
• Run a job every day that pulls the previous day's payments from each gateway API and matches them against your records by gateway id. Anything unmatched goes to a review list a human sees.
• Track fees, refunds and disputes as their own entries, so the sum of what you expect to receive equals the payout the gateway reports. Stripe and Mercado Pago both expose payouts and their breakdown by API.
• For Pix, reconcile by the end-to-end id the Central Bank system assigns to every transaction. It is the one identifier that survives across your bank, your gateway and your records.

When reconciliation is a report you can open in the morning, an integration is finished.

What does a solid integration checklist look like?

Here is the list we work through before we call a gateway integration done. It fits on one page, and it is the difference between a launch and a support queue.

• Hosted checkout or tokenized fields; no raw card data on your servers.
• Every state handled: approved, declined, pending, expired, refunded, disputed, and the customer told what happened in each.
• Webhook signatures verified; raw events stored; 2xx answered within a second; processing from a queue.
• Event ids and payment ids unique in the database; idempotency keys on every request that creates money movement.
• Payment fetched from the gateway API on every event before your record changes.
• Daily reconciliation against each gateway and against the bank payout, with an exceptions list.
• Sandbox and production keys separated by environment; secrets outside the code; a test that runs the full flow with the gateway's test cards before each deploy.
• Failed webhook deliveries checked daily; alerts on unusual decline rates.

How long does it take and what does it cost?

A hosted checkout with one gateway, webhooks done properly and daily reconciliation is a matter of days for a team that has done it before. Adding a second gateway, Pix through a Brazilian provider, subscriptions, or marketplace splits with payouts to third parties each adds a block of work, because each is a new set of states and failure modes. What drives the cost is the number of gateways, the number of payment methods and whether money has to move on to other people, not the framework or the language.

If you are building the rest of the product too, our guide to SaaS billing with Stripe subscriptions covers the subscription state machine, taxes and dunning, and the SaaS development and e-commerce development pages describe what a full build includes. For the payment piece on its own, see our payment gateway integration service: you get a written scope, a fixed price and a delivery date within 24 hours, and typical projects run between 1 and 15 days.

The detail on the work itself

• Payment gateway integration →

  The checklist from this guide, delivered as a fixed-scope integration with webhooks and reconciliation.

• E-commerce development →

  The store around the checkout, for businesses that need the whole thing built.

Frequently asked questions

Keep reading

• SaaS billing: Stripe subscriptions, taxes and dunning →

  How to model subscriptions in Stripe, what US sales tax means for a SaaS, how dunning recovers failed payments, and what changes when you also sell in Brazil.

• Multi-tenant SaaS architecture explained for founders →

  What multi-tenant means, the three ways to separate customer data, how row-level security works in Postgres, and the decisions that are expensive to reverse.

• How to choose a SaaS development company: 12 questions →

  Twelve questions to ask every SaaS development company you shortlist, with the weak answer and the strong answer to each, so proposals stop looking identical.