WooCommerce Custom Payment Gateway Integration: What You Need to Know
By Naveen Verma · Jan 29, 2026
Choosing or building a WooCommerce payment gateway affects security, PCI scope, and how you handle webhooks and refunds. This guide covers the four gateway types, when to use off-the-shelf vs custom, PCI considerations, and what “hardened” integration means (idempotency, webhook verification, retries).
The Four WooCommerce Payment Gateway Types
WooCommerce supports four main gateway patterns. Your choice determines where card data goes and how much PCI scope you have.
| Type | How it works | PCI scope | Examples |
|---|---|---|---|
| Form-based | User is redirected to the processor; data never touches your server. | Low | PayPal Standard, Authorize.net DPM |
| iFrame-based | Payment form loads in an iframe on your checkout; processor hosts the fields. | Low | SagePay Form, PayPal Advanced |
| Direct | Payment fields on your checkout page; you send data to the API. | Higher (use tokenization) | Stripe, Braintree, custom gateways |
| Offline | No online payment (cheque, bank transfer). | None | BACS, Cheque |
Form and iFrame reduce PCI burden because card data never hits your server. Direct gateways require SSL, tokenization (never store card numbers), and often PCI self-assessment.
PCI DSS and Tokenization
If card data touches your server, you have PCI scope. Best practice: never store card numbers. Use the gateway’s tokenization: collect a token (or use hosted fields) and send only the token to your backend. For webhooks, verify signatures and process idempotently (same webhook twice = same result) to avoid duplicate charges or refunds.
When to Use a Plugin vs Custom Gateway
Use an official or trusted plugin when it fits: Stripe, PayPal, Braintree have solid WooCommerce extensions. Build custom when: (1) no good plugin exists (e.g. regional gateways like Zai, PayDollar, Network International), (2) you need idempotency and strict webhook verification, or (3) you need custom logic (partial captures, subscription handling, multi-currency).
| Use a plugin when | Build custom when |
|---|---|
| Stripe, PayPal, Braintree cover your needs | Regional or niche processor with no plugin |
| Standard checkout flow is enough | You need idempotency, retries, audit logs |
| You want quick setup and plugin updates | You need webhook signature verification and idempotent handling |
What Custom Integration Involves
A custom WooCommerce payment gateway extends WC_Payment_Gateway: register the gateway, add settings (API keys, environment), implement process_payment() (charge or create intent), and handle webhooks (payment completed, refunded). Production-grade builds add: idempotency keys for API calls, webhook signature verification, exponential backoff retries, and no raw card storage—only tokens.
Checklist Before Going Live
- SSL (HTTPS) on checkout and any payment-related pages.
- API keys and webhook secrets in environment/config, not in code.
- Webhook endpoint verifies signature and handles duplicate events idempotently.
- Refunds and failures tested; order status stays in sync with the gateway.
FAQ
What are the four types of WooCommerce payment gateways?
Form-based (redirect to processor, e.g. PayPal Standard), iFrame-based (payment loads in iframe), direct (payment fields on checkout, e.g. Stripe), and offline (cheque, bank transfer). Form and iFrame reduce PCI scope; direct requires SSL and tokenization.
Do I need PCI DSS compliance for WooCommerce payments?
If card data touches your server (direct gateway with card fields on your site), you have PCI scope. Use tokenization and never store card numbers; use the gateway’s hosted fields or redirect to keep scope minimal. Most custom integrations use API tokens and webhooks, not raw card data.
When should I build a custom WooCommerce payment gateway?
Build custom when: no suitable plugin exists for your processor (e.g. regional gateways like Zai, PayDollar), you need idempotency and webhook verification, or you need custom logic (refunds, partial captures, subscription handling). Use off-the-shelf Stripe/PayPal plugins when they fit.
We build hardened payment integrations—zero card storage, webhook verification, idempotent processing, and retries. Custom WordPress plugins and API integration for WooCommerce and beyond.
Get in touch