What a payment gateway does and what you need before you start

A payment gateway is software that sits on your website and captures card details, bank account information, or digital wallet data from your customer, then sends that data securely to your processor for authorization. It does not store the card information on your server—that is the gateway's job. Before you integrate one, you need three things: a merchant account (which your processor sets up), API credentials from your gateway provider (usually a key and a secret), and a development environment where you can test without charging real money.

The integration itself means writing code that connects your website to the gateway's servers. If you use a platform like Shopify, WooCommerce, or Square Online, the gateway is often built in and you just flip a switch. If you built your site from scratch or use a custom system, you will write code—usually in the language your site runs on (PHP, Python, JavaScript, Java, etc.)—that calls the gateway's API and handles the response.

The gateway provider gives you documentation that shows exactly which endpoints to call, what data to send, and what format the response comes back in. You test in a sandbox environment first, where transactions are fake and free. Once everything works, you switch to live mode and real money moves.

Key Takeaways

  • You need a merchant account from a processor and API credentials from a gateway provider before you write any code.
  • Most gateways provide a sandbox environment where you can test transactions for free before going live.
  • If you use a hosted platform like Shopify or WooCommerce, the gateway integration is usually a built-in feature you enable in settings.
  • Custom-built sites require you to write code that calls the gateway's API, handle responses, and manage error cases.
  • Never store card data on your own server; the gateway handles that and returns a token you can use for future charges.

Choosing between hosted payment forms and API integration

A hosted payment form means your customer leaves your website, enters their card details on the gateway provider's secure page, and returns to you with a confirmation. Stripe Checkout and PayPal Standard work this way. You do not touch the card data at all, which means you avoid PCI compliance headaches. The downside is less control over the look and feel, and a small percentage of customers abandon the process because they leave your site.

An API integration means the payment form lives on your website. Your customer enters their card details in a form you built, your code sends that data to the gateway's API, and the gateway returns a token or a success/failure response. You have full control over the design and flow, but you are responsible for handling sensitive data securely. This requires either PCI compliance certification (expensive and complex) or a tokenization service where the gateway handles the sensitive part and you only see a token.

Most modern gateways offer a middle ground: a hosted iframe or embedded form. Stripe Elements and Square Web Payments SDK work this way. The form is embedded in your page but the card data never touches your server—the gateway's JavaScript handles it. You get design control and security without the full PCI burden.

Step-by-step integration for a custom website

Start by signing up for a merchant account with a processor (Stripe, Square, PayPal, Authorize.net, etc.). They will give you a dashboard where you can see transactions and manage settings. Then request API credentials—usually a publishable key (safe to put in your front-end code) and a secret key (kept private on your server). Store the secret key in an environment variable, never in your code repository.

Install the gateway's SDK for your language. For Stripe in PHP, you run composer require stripe/stripe-php. For JavaScript, you load their script tag. The SDK handles the API calls and response parsing for you.

Build a payment form on your website with fields for amount, card details, and billing address. If you are using an embedded form like Stripe Elements, you load their JavaScript library and create a form element. If you are building your own form, make sure it is on an HTTPS connection (not HTTP) so the data is encrypted in transit.

Write a server-side endpoint that receives the payment data from your form. This endpoint takes the card token (not the raw card number) and calls the gateway's API to create a charge. The gateway returns a response with a transaction ID, status, and any error messages. Store the transaction ID in your database so you can look it up later.

Handle errors and edge cases: declined cards, network timeouts, duplicate charges. If a charge fails, return a clear error message to the customer. If the network times out, do not charge again—check your database first to see if the charge already went through.

Testing in sandbox mode before going live

Every gateway provider gives you a sandbox environment where you can test without spending money. Log into your dashboard and switch to sandbox mode. Your API credentials change to sandbox credentials, and transactions are fake.

Use test card numbers provided by the gateway. Stripe's test number is 4242 4242 4242 4242. Square's is 4111 1111 1111 1111. You can use any future expiration date and any three-digit CVC. When you charge a test card, the transaction appears in your sandbox dashboard but no real money moves.

Test the happy path first: a successful charge. Then test failures: use a card number that declines (Stripe provides 4000 0000 0000 0002 for this), test a network timeout by disconnecting your internet mid-request, and test a duplicate charge by submitting the same form twice. Make sure your code handles each case without crashing or charging the customer twice.

Once everything works in sandbox, switch your API credentials to live and test with a small real charge (a few cents). Refund it immediately. This confirms your live account is working and your code is talking to the real gateway.

Handling PCI compliance and data security

PCI DSS (Payment Card Industry Data Security Standard) is a set of rules that apply if you handle card data. The core rule: never store raw card numbers on your server. If you use a hosted form or tokenization, the gateway handles this and you are mostly safe. If you build your own form and touch raw card data, you need PCI certification, which requires security audits, firewalls, encryption, and regular testing. It is expensive and complex.

The practical path for most websites: use an embedded form (Stripe Elements, Square Web Payments SDK) or a hosted form (Stripe Checkout, PayPal Standard). The gateway's JavaScript handles the sensitive part, you only see a token, and your PCI burden drops to the lowest level.

Always use HTTPS for your payment pages. Never send card data over HTTP. Store API secret keys in environment variables, not in code. Rotate your keys periodically. Log all transactions but never log card numbers or CVCs.

Common integration mistakes and how to avoid them

Storing card data on your server is the biggest mistake. Do not do it. Use tokenization or a hosted form instead. The gateway will give you a token that represents the card, and you store the token, not the card number.

Charging twice because of a network timeout is the second biggest. If your code does not hear back from the gateway, do not assume the charge failed. Check your database or call the gateway's API to look up the transaction before charging again. Idempotency keys help: you send the same key with each retry, and the gateway ignores duplicate requests with the same key.

Forgetting to test error cases means your live site crashes when a card declines. Test declined cards, network timeouts, and invalid data in sandbox mode. Make sure your code returns a clear error message to the customer and logs the failure for you to investigate.

Hardcoding API keys in your code means anyone who reads your code can use your account. Use environment variables instead. In PHP, read from $_ENV['STRIPE_SECRET_KEY']. In Node.js, read from process.env.STRIPE_SECRET_KEY. Set these variables in your hosting provider's dashboard or in a .env file that you never commit to version control.

Connecting webhooks so you know when payments succeed or fail

A webhook is a message the gateway sends to your server when something happens—a charge succeeds, a refund is issued, a subscription renews. You register a URL on your server, and the gateway posts to that URL with details about the event. This is how you know about transactions that happen outside your website, like a customer's subscription renewing at 3 a.m.

Set up a webhook endpoint on your server that accepts POST requests from the gateway. The gateway will send a JSON payload with the event type and data. Verify the signature (the gateway signs each webhook so you know it really came from them), then update your database. If a charge succeeded, mark the order as paid. If a refund was issued, update the order status.

Webhooks are not instant—they can take seconds or even minutes. Do not rely on a webhook to show the customer their payment succeeded. Show success based on the API response from the charge request. Use webhooks to update your records and send confirmation emails asynchronously.

Frequently Asked Questions

Do I need to know how to code to add a payment gateway?

Not if you use a hosted platform like Shopify, WooCommerce, or Squarespace. The gateway is built in and you enable it in settings. If you built your website from scratch, yes, you need to write code or hire a developer. The code is usually straightforward—most gateways provide code examples in your language.

What is the difference between a payment gateway and a payment processor?

A processor handles the money—they talk to the bank, move funds, and deposit them in your account. A gateway is the software that captures the payment details and sends them to the processor. You usually sign up with a processor, and they give you access to a gateway (or you choose a gateway that works with them).

Can I use multiple payment gateways on the same website?

Yes. You can offer Stripe, PayPal, and Square on the same checkout page. Each has its own API credentials and integration code. The customer picks which one to use, and your code calls the right gateway. This increases your conversion rate because customers can use their preferred method.

What happens if a customer's payment fails?

The gateway returns an error message explaining why (card declined, expired, insufficient funds, etc.). Your code catches this error and shows a message to the customer. They can try a different card or contact their bank. You do not charge them, and the failed attempt does not appear on their statement.

How long does it take to integrate a payment gateway?

For a simple hosted form, a few hours. For an embedded form with error handling and webhooks, a day or two. For a complex custom integration with multiple gateways and subscription support, a week or more. Most of the time goes to testing and handling edge cases, not the initial integration.