AEO & GEO
Payment Gateway API Integration: 8-Step Guide
18 min read
Adam Khaled
Founder, Web25
Quick answer: Payment gateway API integration connects your site or app to a payment provider, so customers can pay by card, usually without card data touching your server. You choose a checkout model, create payments on your server, confirm them with signed webhooks and match payouts to orders. Most small stores should try the gateway’s official plugin first.
Need a second pair of eyes on your checkout? Book a discovery call and tell us what you sell.
Key takeaways
- The checkout model you pick decides who touches card data and how much PCI work lands on you.
- Confirm a payment from a signed webhook, not from the page the customer sees after paying.
- Send an idempotency key with every request that creates a payment, so a retry can’t charge twice.
- A bank payout bundles many charges, refunds and fees, so store the gateway’s payment ID on every order.
- Most stores on WooCommerce or Shopify should start with the gateway’s official plugin or app.
Table of contents
- What is a payment gateway API integration?
- Do you need a custom payment gateway integration, or is a plugin enough?
- Which checkout model should you choose?
- How do you set up a payment gateway API integration in 8 steps?
- What has to happen after the customer pays?
- How do payments reach your accounting or ERP system?
- What should you test before going live?
- What mistakes cause double charges or missing orders?
- Who can build a payment API integration for you?
- FAQ
If you want to take card payments on your own site or app, you’ll end up doing a payment gateway API integration, even when a plugin does most of the work. This guide explains how the pieces fit, which checkout model to pick, how to set it up and what to test before real money moves.
What is a payment gateway API integration?
A payment gateway API integration is the connection between your website or app and a payment provider, so customers can pay by card while the sensitive card data usually stays with the provider. An API is the set of requests two programs use to talk to each other. A payment gateway is the service that takes the card details and passes the payment on.
Three things travel across that connection. Your server sends a request to create a payment, the gateway sends back the result, and later the gateway sends events such as “payment succeeded” or “refund created”. The third part is the one most guides skim, and it’s where orders go missing.
Do you need a custom payment gateway integration, or is a plugin enough?
For most stores on WooCommerce or Shopify, the gateway’s official plugin or app is enough. It handles the payment gateway integration for you and costs less than custom work. Custom work makes sense when you run a custom site or web app, take deposits or bookings, have a multi-step checkout, or need payments to reach an ERP or accounting system.
WooCommerce’s developer docs describe four gateway types: form based, iframe based, direct and offline. A plugin hides that choice from you, which is fine until your process stops fitting it.
If the job goes past a plugin, our guide to custom API integration services explains the general method. The rest of this guide covers what is specific to payments.
Which checkout model should you choose: hosted, embedded or direct?
Choose a hosted page or embedded fields unless you have a strong reason not to. The model decides who touches card data, and that decides how much PCI work you carry. PCI DSS is the card industry’s security standard, and many smaller merchants confirm they meet it with a self-assessment questionnaire called an SAQ.
| Model | Where the customer types card details | Does card data touch your server? | PCI workload | Typical fit |
|---|---|---|---|---|
| Hosted page (redirect) | On the gateway’s own page | No | The newer SAQ A script criterion doesn’t apply to redirects, per PCI SSC FAQ 1588 | Small stores and quick launches |
| Embedded fields (iframe) | In the gateway’s form inside your page | No | The SAQ A script criterion applies, so confirm it with your provider | Custom sites that want the checkout to look like their own |
| Direct API | On your own form | Yes | The largest. Confirm the questionnaire with your acquirer | Platforms with their own card vault and a security team |
The PCI Security Standards Council’s FAQ on the SAQ A criteria says the new script criterion applies to merchants whose pages embed a payment form, such as an iframe, and doesn’t apply to merchants that redirect customers. It took effect on April 1, 2025, and the Council’s FAQ 1588 lists two ways to meet it. You can use script-protection techniques, or you can get confirmation from your PCI DSS compliant provider that its embedded form includes them.
WooCommerce’s docs make the same point from the store side. They say form and iframe gateways post data offsite, which leaves fewer security issues to manage, while direct gateways need server security and may require some level of PCI compliance.
This guide can’t choose your questionnaire for you. The Council’s own advice is to check with your acquirer (your merchant bank) or the card brands.
How do you set up a payment gateway API integration in 8 steps?
To set up a payment gateway API integration, pick the checkout model, get test keys, create payments on your server with an idempotency key, collect card details only in the gateway’s fields, verify signed webhooks, fulfill from the webhook, handle refunds and failures, then test before switching to live keys. The steps below follow that order.
Step 1: Pick the checkout model
Use the table above. If you’re unsure, choose a hosted page, because it keeps card data off your server and gives you the smallest security job.
Step 2: Get test keys and keep secrets out of code
Every gateway gives you test keys and live keys. Start with test keys, keep them in environment variables or a secrets manager, and never put a secret key in front-end code or a public repository.
Name the test and live secrets clearly, so nobody swaps them by accident.
Step 3: Create the payment on your server with an idempotency key
An idempotency key is a unique value you send with a request, so the gateway can tell a retry from a new request. Stripe’s docs say it lets you retry a request without performing the same operation twice.
Stripe suggests V4 UUIDs, allows keys up to 255 characters, and accepts them on all POST requests in API v1. It compares the new parameters with the original request and returns an error if they differ.
Step 4: Collect card details only in the gateway’s page or fields
The customer types the card number into the gateway’s hosted page or embedded fields. Your server gets back a token or a payment ID, never the card number.
Step 5: Build a webhook endpoint that verifies signatures
A webhook is a message the gateway sends to your server when something happens. Anyone can post fake data to a public URL, so verify every event before you act on it.
Stripe signs each event in a Stripe-Signature header that you check against the raw request body. PayPal’s webhook documentation offers a self-check or a verify-signature endpoint.
Step 6: Fulfill from the webhook, not the success page
Mark the order as paid when the verified webhook arrives. Stripe’s fulfillment guide says you can’t rely only on the landing page, because a customer can pay and then lose their connection before the page loads.
The same guide warns that your fulfillment function may run more than once, even at the same time, so it must be safe to repeat.
Step 7: Handle refunds, failed payments and delayed payments
Treat a refund as its own event that updates the order and your books. Show a clear message for declined cards and let the customer try again.
Some payment methods confirm later. Stripe’s guide names ACH direct debit as an example and says it sends a separate event when that payment finally succeeds, so your order status has to wait for it.
Step 8: Test failure paths, then go live and watch
Run the checklist in the testing section below with test keys. Then switch to live keys, place one small real order yourself and watch the first real orders closely, including the webhook log.
What has to happen after the customer pays?
Your server has to verify the signed webhook, answer with a success code quickly and then do the slow work in a queue. The charge is the easy part. The events that follow need more care.
Stripe’s webhook docs set out the rules your endpoint has to live with:
- Return a 2xx code before any complex logic, because a slow response counts as a failure.
- A redirect (3xx) counts as a failure too, so register the final URL.
- Events can arrive twice, so log the event IDs you’ve processed and skip repeats.
- Stripe doesn’t guarantee the order of events, so don’t depend on one arriving first.
Retry windows are short. Stripe retries live events for up to three days with exponential backoff, and PayPal retries up to 25 times over three days before it marks the delivery as failed. Both let you resend by hand, so plan for a gap and add a job that compares your orders with the gateway’s list of payments.
How do payments reach your accounting or ERP system?
Send each paid order to your books with the gateway’s payment ID on it. The bank deposit will never equal one order, because a payout bundles many charges, refunds and fees.
Stripe’s payout reconciliation report shows this. It matches each payout to the batch of payments, refunds, disputes and fees it settles, and the itemized CSV can carry custom metadata so you can match rows to records in your accounting system. The report only covers automatic payouts.
Three habits make the matching easy:
- Store the gateway’s payment ID and your order number on both sides.
- Map each gateway to its own bank or clearing account, as in our Xero WooCommerce integration guide.
- Send orders to the ERP only after payment is confirmed, as in our NetSuite WooCommerce integration guide.
Our Odoo WooCommerce integration guide shows how to map payment methods when the ERP is Odoo.
What should you test before going live?
Test every failure path, not only the happy one. Stripe’s testing page lists test cards for a successful payment, a generic decline, insufficient funds, an expired card, an incorrect CVC and 3D Secure authentication.
Run this checklist with test keys:
- A successful card payment.
- A generic decline, and a decline for insufficient funds.
- An expired card and a wrong CVC.
- A card that needs 3D Secure authentication.
- The same webhook delivered twice.
- A webhook that arrives before the customer reaches the thank-you page.
- A full refund and a partial refund.
- A delayed payment that later succeeds, and one that later fails.
Don’t test with real cards in live mode. Stripe says its Services Agreement prohibits that.
Stripe, PayPal, PCI SSC and WooCommerce details were checked against their documentation in October 2026.
What mistakes cause double charges or missing orders?
Each of these comes from skipping one of the checks above.
- Retrying a payment request without an idempotency key.
- Marking orders paid from the success page.
- Leaving the webhook endpoint unsigned, so anyone can post a fake “paid” event.
- Letting a framework rewrite the raw request body, which breaks Stripe’s signature check.
- Blocking the webhook route with CSRF protection or a redirect.
- Mixing up test and live secrets.
- Having no alert when deliveries fail.
Who can build a payment API integration for you?
If the gateway’s official plugin covers your checkout, you may not need custom work, and we’ll say so. A plugin is the cheaper and quicker route for a standard store.
Web25 is our agency. This guide covers it alongside alternatives.
We build custom integrations between WooCommerce stores and accounting software, then keep them monitored afterward. Web25 has no public payment gateway case study, so treat this guide as method, not a track record.
The closest public proof is the Mirael3D POHODA case study. It’s an accounting integration, not a payment one, but the safeguards carry over: a dry run before writing anything, a log-only mode and blocked duplicates.
Web25 builds checkout and payment integrations as part of its ecommerce work and its backend and API work, and the ecommerce page lists card payments, digital wallets and most major payment gateways.
FAQ
A payment gateway takes the card details and passes the payment request on. A processor moves the money through the card networks, and a merchant account receives it. Many providers bundle all three, so you often deal with one company. Check what your provider includes, because some sell the gateway and the processing separately.
Yes. Many sites offer a card gateway and PayPal side by side. Each one has its own keys, webhook endpoint, test cases and payouts, so every extra gateway adds setup and reconciliation work. Map each gateway to its own clearing account in your accounting system so the deposits stay easy to match.
Yes, in practice. WooCommerce's developer docs say direct gateways need server security. Stripe requires an HTTPS webhook endpoint in live mode and supports only TLS 1.2 and 1.3. A hosted payment page runs on the gateway's own secure site, but your own pages and webhook endpoint still need HTTPS.
Use webhooks. Stripe's fulfillment guide says automatic fulfillment with webhooks is required if you sell subscriptions, because later payments and state changes happen after checkout is over. Your server must expect renewal, failure and cancellation events weeks or months after the first charge, and update the customer's access each time.
The gateway keeps retrying for a limited time, then marks the delivery as failed. Stripe lets you resend an event by hand from the Dashboard for up to 15 days after it was created, or with the Stripe CLI for up to 30 days. Set an alert for failed deliveries so you can resend before those windows close.
No. Let the gateway store the card and give you a token or a saved payment method ID, then keep only that ID. Storing card numbers yourself means card data reaches your server, which puts you in the heaviest part of the PCI workload. The gateway's tokens give you repeat payments without that burden.
It depends on a few things you can list before you ask for a quote. The checkout model, the number of payment methods, whether you need subscriptions or refunds from your own admin screen, an accounting or ERP sync and how much failure testing you want all change the schedule. A plugin takes far less time than custom code.
What to do next
Write down which checkout model you want and which events your orders depend on, so your payment gateway integration has a clear scope. Then check that your plan covers signed webhooks, an idempotency key and a way to match payouts to orders. If you want a second opinion, book a discovery call and describe your checkout.
Written by Adam Khaled, Founder, Web25. Last updated October 18, 2026.
