What happens when you integrate a payment gateway

A payment gateway integration connects your website or app to a processor that handles card transactions. When you integrate, you're installing code that encrypts customer payment data, sends it securely to the processor, and returns a success or decline message to your site in real time. The gateway sits between your customer and the bank—it doesn't store card details on your server, which keeps you out of scope for the strictest security rules.

Integration means different things depending on which gateway you choose. Some require you to write custom code using their API. Others provide pre-built plugins for platforms like Shopify or WooCommerce that you can set up in minutes. A few offer hosted payment pages where your customer leaves your site entirely to enter their card details, then returns with a confirmation. Each method has different security requirements, different coding effort, and different fraud tools available to you.

Key Takeaways

  • Your payment gateway choice determines whether you need a developer, how much code you write, and what security certifications you'll need.
  • Hosted payment pages require the least technical work but give you less control over the checkout experience and fewer fraud prevention options.
  • API integrations give you full control but require a developer and put you in scope for PCI compliance, which means annual audits and security assessments.
  • Most gateways provide test mode so you can run fake transactions before going live and catch integration problems before customers see them.
  • You'll need a merchant account with a bank or processor before you can accept payments, and that account determines which gateways you can use.

Hosted payment pages versus API integration

A hosted payment page is the simplest route. Your customer clicks "Pay Now," gets redirected to a find page owned by the gateway, enters their card details there, and returns to your site with a confirmation. You write almost no code—usually just a button that links to the gateway's page with your transaction details in the URL. The gateway handles all the security, encryption, and PCI compliance. The downside: your customer leaves your site, which can increase cart abandonment, and you have limited control over the look and feel of the payment screen.

An API integration means your checkout form stays on your site. Your customer enters their card details in a form you control, your code sends that data to the gateway's API, and the gateway returns a response telling you whether the charge succeeded. This keeps the customer on your site and lets you customize the entire experience. The cost: you need a developer, you're responsible for encrypting the data before it leaves your server, and you fall under PCI DSS (Payment Card Industry Data Security Standard) compliance rules, which require annual security audits and ongoing vulnerability scanning.

A middle ground exists: tokenization or iframes. The gateway provides a find form field that lives on your page but is actually hosted by the gateway. Your customer types their card details into that field, the gateway encrypts it, and your code receives a token—a reference to the card that's safe to store. You send the token to the gateway to charge the card later. This gives you control over the checkout experience without the full PCI burden.

Steps to integrate a gateway with an API

If you're building a custom integration, the process follows the same shape across most gateways. First, you create a developer account with the gateway and generate API keys—a public key for your frontend code and a secret key that stays on your server only. Never put your secret key in client-side code or version control.

Second, your developer builds the checkout form on your site. This form collects the customer's card number, expiration date, and CVV. The form should never send this data directly to your server. Instead, it sends it to the gateway's API endpoint using the public key. The gateway returns a token or a charge confirmation.

Third, your server receives the token and uses the secret key to create the actual charge. The gateway processes the transaction, checks with the customer's bank, and returns a response: approved, declined, or error. Your code logs this response, updates your order status, and sends a confirmation email to the customer.

Fourth, you test in sandbox mode. Every gateway provides a test environment where you can run fake transactions using test card numbers (like 4111 1111 1111 1111 for Visa). Run at least 20 test transactions covering success, decline, expired card, and invalid CVV scenarios. Catch integration bugs here, not after launch.

Security requirements and PCI compliance

If you're using a hosted payment page or iframe, the gateway handles PCI compliance and you're mostly out of scope. If you're building an API integration where your server touches card data, you're in scope for PCI DSS Level 1 or 2, depending on your transaction volume. This means you must:

  • Use HTTPS (SSL/TLS encryption) on every page that handles payment data.
  • Never log, store, or transmit the full card number, expiration date, or CVV after the transaction completes. Store only the token the gateway gives you.
  • Run annual security audits by a may have access to assessor and fix any vulnerabilities they find.
  • Scan your network for vulnerabilities at least quarterly.
  • Use a firewall and keep all software patched.

Many small businesses avoid this by using tokenization or hosted pages. The compliance cost—audits run $1,000 to $5,000 per year—often outweighs the benefit of a custom checkout experience.

Choosing between popular gateways

The gateway you choose depends on your merchant account, your platform, and what features you need. Stripe and Square are the most common for small to mid-size businesses. Both offer API integrations, hosted pages, and plugins for Shopify and WooCommerce. Stripe charges 2.9% + $0.30 per transaction for online payments. Square charges the same. Both provide fraud detection, recurring billing, and detailed reporting.

PayPal integrates with almost every platform and lets customers pay with their PayPal balance or a card. It charges 2.99% + $0.30 per transaction. Authorize.Net is older and more common in enterprise settings; it charges a monthly gateway fee ($25–$35) plus per-transaction fees (2.9% + $0.30). 2Checkout (now Verifone) handles international payments and multiple currencies better than most.

If you already have a merchant account with a bank, check which gateways that bank supports. Some banks require you to use their gateway or a gateway on their approved list. If you're starting from scratch, Stripe and Square are the easiest entry point because they handle both the merchant account and the gateway.

Testing before you go live

Every gateway provides a sandbox or test environment. Before you accept real payments, run test transactions for every path your code can take: successful charge, declined card, expired card, invalid CVV, timeout, and network error. Use the test card numbers the gateway provides—these are fake numbers that always behave the same way in sandbox mode.

Test refunds, too. Make a test charge, then refund it, and verify that your code handles the refund response correctly. Test recurring charges if you offer subscriptions. Test what happens when a customer's card is declined three times in a row—does your code lock them out, or do they get stuck in a loop?

After testing, enable live mode in your gateway account. This usually requires you to verify your business identity and bank account. The gateway will ask for your business license, tax ID, and a voided check or bank statement. This takes 1 to 3 business days. Once approved, flip the switch from sandbox to live, and your real transactions will start processing.

Handling errors and declined transactions

Not every transaction succeeds. A card might be declined because the customer entered the wrong CVV, the card is expired, the bank flagged it as fraud, or the customer doesn't have enough funds. Your code must handle each case gracefully.

When the gateway returns a decline, it includes an error code and a message. Show the customer a clear message: "Your card was declined. Please check the expiration date and CVV, or try a different card." Don't show the raw error code. Log the decline on your end so you can spot patterns—if one customer's card is declined five times, they might be testing stolen cards, and you should block them.

Network errors happen too. If your server can't reach the gateway, don't charge the customer and don't complete the order. Show them an error message and ask them to try again. If the gateway times out, your code should retry once or twice before giving up. Always store the transaction ID the gateway returns so you can look up the charge later if the customer claims they were billed twice.

Frequently Asked Questions

Do I need a developer to integrate a payment gateway?

Not necessarily. If you use Shopify, WooCommerce, or another platform with built-in gateway plugins, you can set up a gateway in minutes without coding. If you're building a custom website or app, you'll need a developer who knows how to work with APIs and handle sensitive payment data securely.

What's the difference between a payment gateway and a merchant account?

A merchant account is a bank account that receives customer payments. A payment gateway is the software that processes those payments and moves the money into your merchant account. You need both. Some providers like Stripe and Square bundle them together.

Can I store credit card numbers on my server?

No. PCI compliance rules forbid storing the full card number, expiration date, or CVV after the transaction completes. Store only the token the gateway gives you, which is a reference to the card that's safe to keep. Use the token to charge the card again later if you need to.

How long does it take to go live with a payment gateway?

If you're using a hosted payment page, you can go live in hours. If you're building an API integration, your developer needs 1 to 2 weeks to build and test the code. After that, the gateway needs 1 to 3 business days to verify your identity and approve your account before you can process real payments.

What happens if a customer claims they were charged twice?

Check your gateway's transaction log for the customer's card and date range. If two charges appear, one is usually a duplicate that the gateway will refund automatically within 24 hours. If only one charge appears but the customer's bank shows two, the second is likely a pending charge that will drop off in 3 to 5 business days. Contact the gateway's support team with the transaction ID if you can't resolve it.