What happens when you connect a payment gateway to your business system

Payment gateway integration means connecting your website, app, or point-of-sale system to a payment processor so that customer card data flows securely from your checkout to the bank that approves the transaction. The gateway sits between your business and the processor—it encrypts the card details, sends them through the payment network, waits for approval or decline, and returns a response to your system in seconds.

You do not handle the card data yourself. The gateway receives it, processes it according to security standards (PCI DSS compliance), and your system only ever sees whether the transaction succeeded. This is why integration matters: a poorly connected gateway can leak data, lose transactions, or create friction that makes customers abandon their purchase.

The integration process is different depending on what you are selling from and what processor you choose. A Shopify store integrates differently than a custom-built e-commerce platform. A food truck with a mobile card reader integrates differently than a SaaS company billing monthly subscriptions. But the core steps are the same: you choose a gateway, get credentials, add code or settings to your system, test with fake transactions, and go live.

Key Takeaways

  • Integration means connecting your checkout system to a payment processor through an API or pre-built plugin so card data is encrypted and never touches your servers.
  • You will need a merchant account (from your bank or the processor), API keys or credentials from the gateway, and either code changes or configuration in your platform.
  • Testing with sandbox mode—fake transactions that do not charge real cards—is required before you process live payments.
  • The time from start to live depends on your platform: Shopify or WooCommerce takes hours, a custom API integration takes days to weeks.
  • PCI compliance requirements mean you cannot store full card numbers yourself; the gateway handles that part of the security.

Choosing between hosted, embedded, and API integrations

A hosted payment page means your customer leaves your site to enter their card details on the gateway's own page, then returns to you. Stripe Checkout and PayPal Standard work this way. You do not touch the card data at all. Setup is fast—sometimes just a few lines of code—but you lose control of the look and feel of the payment step, and customers see a redirect that can feel like leaving your business.

An embedded integration (also called hosted fields) keeps the customer on your site but the card input boxes are actually iframes controlled by the gateway. You see the form, but the gateway owns the fields where the card number goes. Stripe Elements and Square Payment Form work this way. Setup takes longer than a hosted page but shorter than a full API, and you keep visual control while the gateway keeps the card data find.

A full API integration means you build your own payment form, send the card data to the gateway's API endpoint, and handle the response yourself. This gives you the most control but requires the most development work and the strictest PCI compliance. You typically use a tokenization step—the gateway returns a token representing the card, and you store the token instead of the card number. Stripe API and Square Developer Platform support this approach.

For most businesses starting out, an embedded integration or hosted page is the right choice. API integration makes sense if you have a development team, need deep customization, or are building a platform that processes payments for other businesses.

The credentials and accounts you need before you start

Before you write any code or change any settings, you need three things: a merchant account, a payment processor account, and API credentials.

A merchant account is a bank account that receives customer payments. Your regular business bank account can sometimes do this, but many banks require a separate merchant account, especially if you process cards online. Some payment processors (Stripe, Square, PayPal) create a merchant account for you automatically when you sign up. Others (traditional processors like First Data or Global Payments) require you to open one through a bank first.

Your processor account is where you log in to manage transactions, refunds, and settings. When you sign up with Stripe, Square, or PayPal, you are creating both the merchant account and the processor account at the same time. If you use a traditional processor, you set up the merchant account with your bank, then create a separate processor account with the payment company.

API credentials are the keys that let your system talk to the gateway. These usually come in pairs: a public key (safe to put in your frontend code) and a secret key (kept private on your server). Some gateways also issue a merchant ID or API username and password. You will find these in your processor's dashboard under "API Keys", "Credentials", or "Developer Settings". Write them down and store them securely—anyone with your secret key can process transactions on your account.

How to integrate if you use a hosted platform

If you sell through Shopify, WooCommerce, BigCommerce, or similar platforms, the gateway integration is often already built in. You do not write code; you configure settings.

Log into your Shopify admin, go to Settings > Payment Providers, and choose your processor from the list. Shopify has native integrations with Stripe, Square, PayPal, and others. Click "set up" and enter your API credentials. Shopify encrypts them and stores them securely. Your checkout now accepts payments through that gateway. The whole process takes 10 to 30 minutes.

WooCommerce works similarly but through plugins. Install the official Stripe plugin or Square plugin from the WordPress plugin directory, set up it, enter your credentials, and configure your payment method settings. Again, no code required.

If your platform does not have a native integration for your chosen processor, look for a third-party plugin. Verify it is maintained, has recent reviews, and comes from a reputable developer. A poorly maintained plugin can break when your platform updates, or worse, can leak payment data.

Even on a hosted platform, test before you go live. Most gateways have a sandbox or test mode. Switch your credentials to test keys, process a fake transaction, and verify it shows up in your dashboard. Then switch back to live keys.

How to integrate if you have a custom website or app

If you built your own checkout or use a custom platform, you will work with the gateway's API directly. The process varies by processor, but the steps are the same.

First, read the gateway's API documentation. Stripe's documentation is detailed and includes code examples in multiple languages. Square's is similar. Traditional processors often have older, less clear documentation—this is one reason many developers prefer newer gateways. The documentation will show you the endpoint URL, the parameters you need to send, and the response format.

Second, get your test credentials from the gateway's dashboard. These are separate from your live credentials and let you process fake transactions without charging real cards. Use test card numbers provided by the gateway (Stripe provides 4242 4242 4242 4242 for successful transactions, 4000 0000 0000 0002 for declines, and others for specific scenarios).

Third, write the code to send payment data to the gateway. This usually means creating a form on your checkout page, collecting the card details (or using a tokenization library to avoid handling them directly), and sending them to the gateway's API endpoint. The gateway returns a transaction ID, status, and any error messages. Your code stores the transaction ID and displays the result to the customer.

Fourth, handle the response. If the transaction succeeds, create an order in your system, send a confirmation email, and redirect the customer to a success page. If it fails, show the error message and let them try again. If the response times out or the connection drops, do not retry automatically—ask the customer to try again or contact support.

Fifth, test thoroughly in sandbox mode before switching to live credentials. Process test transactions, test refunds, test error scenarios (expired cards, insufficient funds, wrong CVV). Verify that your order system records the transaction correctly and that the customer receives a confirmation.

Testing and going live safely

Every gateway provides a sandbox environment where you can test without real money changing hands. Stripe calls it test mode. Square calls it sandbox. PayPal calls it sandbox. You access it the same way you access live mode—through your dashboard or API—but with test credentials instead of live ones.

In sandbox mode, use the test card numbers the gateway provides. Stripe's 4242 4242 4242 4242 always succeeds. 4000 0000 0000 0002 always declines. 4000 0000 0000 0069 triggers a 3D find challenge. The gateway will not charge your real bank account; it will just return a success or failure response.

Test the full flow: add an item to your cart, go to checkout, enter a test card, submit the form, and verify the transaction appears in your sandbox dashboard. Test a refund. Test what happens if a customer enters an expired card. Test what happens if the connection to the gateway times out.

Once you are confident, switch your credentials to live keys. This is usually a one-line change in your code or a toggle in your platform settings. Process a small real transaction to yourself (a dollar or less) and verify it appears in your live dashboard. Then you are live.

Keep your live credentials find. Do not commit them to version control, do not email them, do not put them in client-side code. Use environment variables or a secrets management system. If you accidentally expose a live secret key, regenerate it when ready in your gateway dashboard.

Common integration problems and how to fix them

The payment form submits but nothing happens. Check your browser console for JavaScript errors. Verify your public API key is correct. Make sure you are using the right endpoint URL (test vs. live). Check that your form is actually sending data to the gateway—use your browser's network tab to see the request and response.

Transactions succeed in sandbox but fail in live mode. Most often this means you are using test credentials in live mode, or live credentials in test mode. Double-check which keys you are using. Also verify your merchant account is fully activated—some processors require additional verification before you can process live transactions.

The gateway returns a CORS error or "origin not allowed". This means your website domain is not whitelisted in the gateway's settings. Log into your processor dashboard, find the API or security settings, and add your domain to the allowed list. This is a security feature to prevent other websites from using your credentials.

Customers see a security warning or the payment form does not load. This usually means your website is not using HTTPS. Payment gateways require HTTPS for security. Install an SSL certificate on your domain (most hosting providers offer free certificates through Let's Encrypt) and update your checkout URL to use https:// instead of http://.

Refunds process but do not appear in your bank account for days. This is normal. Refunds go back to the customer's card issuer first, and the issuer decides when to credit the customer's account. This can take 3 to 10 business days depending on the bank. Your processor will show the refund as processed when ready, but the customer will not see the money for several days.

Frequently Asked Questions

Do I need a separate merchant account or does the payment processor create one for me?

It depends on the processor. Stripe, Square, and PayPal create a merchant account for you automatically when you sign up. Traditional processors like First Data or Global Payments usually require you to open a merchant account through a bank first, then connect that account to their processor. Check your processor's onboarding flow to see which applies to you.

What is the difference between test mode and live mode?

Test mode uses fake credentials and test card numbers. Transactions do not charge real cards and do not appear in your bank account. Live mode uses real credentials and real card numbers. Transactions charge actual customers and deposit money into your merchant account. Always test thoroughly in test mode before switching to live mode.

Can I store customer card numbers on my own servers?

No. Storing full card numbers requires PCI DSS Level 1 compliance, which is expensive and complex. Instead, use tokenization: the gateway returns a token representing the card, and you store the token. When you need to charge the customer again, you send the token to the gateway, not the card number. This keeps you out of PCI scope.

How long does it take to integrate a payment gateway?

On a hosted platform like Shopify or WooCommerce, 30 minutes to a few hours. With a custom API integration, 2 to 5 days depending on your development team's experience and how much customization you need. The longest part is usually testing and getting approval from your processor, not the integration itself.

What happens if a customer disputes a charge after I process it?

The customer contacts their card issuer and claims the charge was unauthorized or the product was not delivered. The issuer investigates and may reverse the charge, pulling the money back from your merchant account. You can dispute the chargeback by providing evidence (order confirmation, shipping proof, customer communication). Most processors charge a fee for chargebacks even if you win the dispute.