Integrating a payment gateway API is where a merchant account becomes a working checkout. For high-risk merchants it matters even more: the way you integrate affects your approval rates, your chargeback ratio, your PCI DSS obligations and how quickly you can move volume between acquirers if you need to.
This guide walks through a payment gateway API integration step by step: choosing an integration method, setting up sandbox and live environments, tokenisation, 3D Secure, authorisation and capture, webhooks, idempotency, testing and the go-live checklist. If you want the background on what payment APIs are and how to secure them, start with our guide to payment APIs.
Key takeaways
- Choose the integration method first: hosted payment page, embedded fields or a direct API. It decides your PCI DSS scope and how much you build.
- Build against the sandbox, with separate keys, webhook URLs and logs for test and live.
- Never send raw card data through your servers unless you are ready to be PCI DSS compliant for it. Use the gateway’s tokenisation.
- Treat webhooks as the source of truth for payment status, and make every request idempotent so retries never charge twice.
- High-risk integrations need extra pieces: 3D Secure handling, clear descriptors, dispute and alert data, and the ability to route to more than one acquirer.
Step 1: Choose your integration method
Most gateways offer three ways to connect. The choice affects your checkout, your development effort and your PCI DSS scope.
| Method | How it works | Effort | Typical PCI DSS scope |
|---|---|---|---|
| Hosted payment page | The customer is redirected to, or shown in a frame, a payment page hosted by the gateway. | Lowest | Smallest, usually SAQ A |
| Embedded fields | Card fields from the gateway are embedded in your checkout and return a token to your page. | Medium | Usually SAQ A or SAQ A-EP, depending on how the fields are loaded |
| Direct API (server-to-server) | Your server collects card data and sends it to the gateway’s API. | Highest | Full scope, usually SAQ D or a full assessment |
Your acquirer decides which SAQ applies, so confirm it before you build. Most merchants are best served by embedded fields: a checkout under your own brand with card data kept off your servers.
Platform plugins, for example for WooCommerce, or apps on platforms such as Shopify, are a fourth route. They are quick, but limited to what the plugin supports. On Shopify, check whether your gateway is supported on your plan and whether your products are allowed under the platform’s own rules, because platform rules apply on top of your acquirer’s.
Step 2: Set up credentials and environments
- Separate test and live. Use different API keys, webhook endpoints, databases and logs for sandbox and production. Never test with live keys.
- Store keys as secrets. Keep API keys in a secrets manager or environment variables, never in code repositories or front-end code.
- Restrict access. Allow-list your server IP addresses if the gateway supports it, and give each environment its own key.
- Plan key rotation. Know how to rotate keys without downtime before you need to.
Step 3: Collect payment details with tokenisation
With embedded fields or a hosted page, the gateway collects the card details and returns a token to your checkout. Your server sends that token, not the card number, to create the payment. Stored tokens let you charge returning customers and subscriptions without ever holding card data. See our guide to tokenisation.
Collect the data issuers and fraud tools need as well: billing address, email, IP address and device data. Richer data improves both fraud screening and approval rates.
Step 4: Handle 3D Secure and Strong Customer Authentication
For most online card payments in the EEA and UK, Strong Customer Authentication applies, and 3D Secure is how card payments meet it. Your integration needs to:
- send the data 3D Secure 2 needs, so more payments can be approved without a challenge;
- show the challenge, in a frame or redirect, when the issuer asks for one, and resume the payment afterwards;
- handle each outcome: authenticated, challenge failed, issuer not available, or exempt;
- flag merchant-initiated payments such as subscription renewals correctly, so they are not sent for authentication.
Test the challenge flow on mobile as carefully as on desktop. A broken challenge on a phone is one of the most common causes of lost sales after a new integration.
Step 5: Authorise, capture and refund
- Authorisation reserves the funds and tells you whether the issuer approved the payment.
- Capture takes the money. Digital goods are usually captured straight away. Physical goods are usually captured at shipping.
- Void cancels an authorisation that hasn’t been captured.
- Refund returns captured money, fully or partly.
Store the gateway’s transaction ID, your own order ID, the decline code and the 3D Secure result for every attempt. You’ll need them for reconciliation, disputes and approval analysis.
Step 6: Use webhooks for payment status
Many payment events happen after the customer has left your page: a delayed authorisation, a capture, a refund, a chargeback, a subscription renewal. Gateways report them through webhooks. Good webhook handling means:
- Verifying every webhook with the signature the gateway provides before acting on it.
- Responding quickly with a success status, then processing the event in the background.
- Expecting duplicates and out-of-order events. Store event IDs and ignore events you have already processed.
- Not relying only on the browser redirect. Customers close tabs. The webhook, not the return page, should mark an order as paid.
Step 7: Make requests idempotent
Network timeouts happen. If your server retries a payment request without protection, the customer can be charged twice. Most payment APIs support an idempotency key: a unique value you send with each request, so that a retry with the same key returns the original result instead of creating a new payment. Generate one key per payment attempt and store it with the order.
Step 8: Recurring billing
For subscriptions, the first payment is usually customer-initiated and authenticated with 3D Secure, and the card is stored as a token. Renewals are then merchant-initiated payments referencing the original transaction. Your integration should:
- mark initial and repeat payments correctly;
- handle expired and replaced cards, using the gateway’s card updater service if it offers one;
- retry declines carefully, only on recoverable decline codes, with spacing between attempts, because card schemes restrict excessive retries.
Read more in our recurring billing guide.
High-risk considerations most guides miss
More than one acquirer
High-risk merchants often process through more than one merchant account, for redundancy or because different acquirers perform better in different markets. Design your integration so the acquirer or merchant ID is configurable, not hard-coded. BIN routing and payment orchestration build on this.
Descriptors
Make sure the billing descriptor and support contact your customers see match what your checkout and receipts say. Many high-risk businesses use a discreet descriptor, which makes showing it at checkout even more important.
Disputes and alerts
Pull chargeback and dispute events into your systems through the API or webhooks, and connect pre-dispute alerts if your provider supports them, so you can refund before a dispute becomes a chargeback. Every chargeback counts towards card scheme monitoring such as Visa VAMP.
Logging without leaking
Log request IDs, response codes, decline reasons and 3D Secure results, but never full card numbers, CVV codes or authentication data. Mask anything sensitive in support tools and screenshots.
Testing and go-live checklist
- Approved, declined and error responses, including timeouts.
- 3D Secure frictionless, challenge passed, challenge failed and abandoned.
- Full and partial refunds, voids and captures.
- Webhook signature checks, duplicates and out-of-order events.
- Retries with the same idempotency key.
- Subscription renewal, expired card and cancellation.
- Mobile and desktop checkouts in your main browsers.
- Live keys, live webhook URLs and production logging switched on, and test data removed.
- A small live transaction and refund before you send traffic.
Your acquirer will also review your website before going live, so check our list of payment gateway website requirements.
Frequently asked questions
How do I integrate a payment gateway API?
Choose an integration method, get sandbox credentials, collect card details through the gateway’s hosted page or embedded fields to get a token, create payments from your server, handle 3D Secure and webhooks, test every outcome in the sandbox, then switch to live keys and run a small live payment.
What is the difference between a hosted payment page and an API integration?
A hosted payment page is run by the gateway, so card data never touches your site and your PCI DSS scope stays small. A direct API integration gives you full control of the checkout, but card data passes through your systems, which brings much more PCI DSS responsibility.
Do I need PCI DSS compliance if the gateway handles card data?
Yes, but usually at a lower level. With a hosted page or embedded fields you typically complete a short self-assessment questionnaire. Your acquirer confirms which one applies.
What are webhooks used for in payment integrations?
Webhooks are messages the gateway sends to your server when something happens to a payment, such as an authorisation, capture, refund, chargeback or renewal. They are the most reliable way to keep order status correct.
How do I avoid charging a customer twice?
Send an idempotency key with each payment request and reuse it when you retry. The gateway then returns the original result instead of creating a second payment.
Can I integrate more than one payment gateway?
Yes. Many high-risk merchants use more than one acquirer or gateway for redundancy and better approval rates. Keep the provider configurable in your code, or use a payment orchestration layer.
How should I handle customers who fail 3D Secure?
Show a clear message, let them try again or use another payment method, and log the result. Repeated failures from the same customer can be a fraud signal.
Next step
A clean integration starts with the right merchant account. Fasto works with adult, subscription, nutraceutical, gaming, dating and hospitality merchants. Approval typically takes two to three weeks.
Get a free quote, or read more about our high-risk payment gateway.
