Building a WooCommerce Payment Gateway Plugin in 2026

A custom WooCommerce payment gateway plugin is one of the most lucrative pieces of WooCommerce work — every regional gateway needs one, every fintech rebuild needs one, every enterprise WooCommerce migration needs one. It is also one of the highest-stakes types of plugin: a bug touches money.

This tutorial walks the architecture I use on every payment-gateway plugin: WC_Payment_Gateway class structure, webhook design for async confirmations, tokenization for saved cards, PCI scope minimization, idempotency, and the 5 places gateway plugins commonly leak money in production.

Quick verdict: extend WC_Payment_Gateway, never store raw card data, always tokenize via the gateway’s tokenization endpoint, and treat webhooks as the source of truth (not the redirect-back URL). Skip any of these and you will lose money or fail PCI compliance.

WooCommerce payment gateway plugin: quick reference

If you are evaluating WooCommerce payment gateway plugin for your next project, you are weighing real trade-offs between cost, complexity, ownership, and time-to-launch. The right WooCommerce payment gateway plugin decision depends on a handful of variables — team capacity, scope clarity, and how much ongoing maintenance you can absorb. The summary below is the 60-second version; the rest of this guide unpacks the nuance.

• WooCommerce payment gateway plugin pricing typically ranges based on scope clarity, integration count, and ongoing support requirements.
• WooCommerce payment gateway plugin timelines vary from days (small scope) to months (enterprise scope) depending on complexity.
• The biggest variable in WooCommerce payment gateway plugin is requirements clarity at the brief stage — vague briefs produce vague quotes.
• Vendor selection for WooCommerce payment gateway plugin matters more than tool selection — the right team beats the right stack.
• WooCommerce payment gateway plugin ROI is positive when scope is bounded, deliverables are specified, and success criteria are measurable.

For complementary perspectives on WooCommerce payment gateway plugin, the WooCommerce developer documentation and WordPress plugin handbook resources cover adjacent angles worth reviewing alongside this guide. They focus on the underlying technology and standards — this post focuses on the WooCommerce payment gateway plugin decision specifically.

When you revisit your WooCommerce payment gateway plugin approach in 12 to 24 months, three signals usually indicate a refresh is justified. First, the original brief no longer matches business reality — product, audience, or operational scope has shifted. Second, the underlying technology has moved forward enough that the WooCommerce payment gateway plugin decision made under previous constraints would be different today. Third, ongoing maintenance overhead has crept up beyond what was forecast at launch. None of these are emergencies on their own; together they signal it is time to revisit fundamentals rather than patch around them.

WooCommerce payment gateway architecture

Every gateway plugin follows the same shape:

• Gateway class extends WC_Payment_Gateway (or WC_Payment_Gateway_CC for saved cards)
• Settings UI via init_form_fields()
• process_payment() — kicks off the payment, returns redirect or success
• Webhook handler — receives async confirmations from the gateway
• Refund handler via process_refund()
• Token management — saves payment methods for future use
• Admin order screen extensions — show transaction details, allow manual refund

PCI compliance — what you must NOT do

Building a custom WooCommerce payment gateway plugin is the fastest way to expand your PCI scope (and your audit cost). Stay out of scope:

• NEVER store raw card numbers in your DB, in logs, or in error messages
• NEVER handle card data on your server — use the gateway’s tokenization SDK on the client
• USE Payment Element / iframe / redirect so card data never touches your code
• Tokenize first, charge token — the token is safe to store; the card is not
• Encrypt API credentials at rest if your hosting allows

PCI scope reality: Done correctly with tokenization, your custom gateway never touches card data. Your PCI scope stays at SAQ-A (the easiest level). Touch card data once and you balloon to SAQ-D ($10k+ annual audit fees).

process_payment() — the critical method

process_payment( $order_id ) is the heart of every gateway. It must:

• Create the payment intent on the gateway side
• Save the payment intent ID on the WooCommerce order
• Return one of: redirect (3D Secure / external auth) OR success (if synchronous)
• Be idempotent — re-running with the same order_id should not double-charge

Webhook handlers — the source of truth

Never trust the redirect-back URL alone. The user might close the browser before the redirect lands. The gateway sends webhooks to confirm the actual payment state — these are the source of truth for whether the order is paid.

• Register webhook endpoint via register_rest_route with permission_callback that validates the gateway’s signature
• Match incoming events to WooCommerce orders via the saved payment intent ID
• Update order status atomically (use DB transactions for HPOS)
• Reply 200 fast — gateways retry on timeout, retries cause double-processing if you are slow
• Log every webhook event with payload (sanitized) for debugging

Tokenization for saved cards

For repeat customers, tokenize the payment method on first purchase. Subsequent payments use the token. Implementation:

• Subclass WC_Payment_Token_CC or roll your own type
• Save token via $token->save() after first successful payment
• On checkout, present saved tokens via the WC token UI
• Charge against the token via your gateway’s “charge stored payment method” API
• Handle expired tokens gracefully (gateway will return decline; ask user for fresh card)

Refund handling

process_refund( $order_id, $amount, $reason ) handles refunds initiated from the WooCommerce admin. Make it:

• Idempotent (re-running should not double-refund)
• Partial-refund aware (some gateways require special API for partials)
• Logged with full request/response for support
• Update order metadata with refund ID from gateway

Common money-leak bugs in WooCommerce payment gateway plugins

After auditing many gateway plugins, these 5 bugs leak money the most:

• No idempotency on process_payment — refresh on the redirect double-charges
• Webhook signature not verified — anyone can fake a “paid” event
• Redirect-back trusted — user closes browser, order stays “pending” forever
• Currency mismatch — gateway charges in cents, plugin assumes dollars
• Refund amount not validated — partial refunds can refund more than the original charge

Testing a payment gateway plugin

Test before production. Every gateway has a test/sandbox mode:

• Test successful charge with each card type the gateway accepts
• Test 3D Secure / SCA flow if applicable
• Test declined card (gateway-provided test card numbers)
• Test expired card scenario
• Test refund — full and partial
• Test subscription renewal (if supporting subs)
• Test webhook with simulated payload
• Test browser-back during 3DS flow
• Test refresh on success page

Productionization checklist

Before you ship a WooCommerce payment gateway plugin to a real store, every item below should be ✓:

• API credentials in encrypted storage, not source code
• Webhook endpoint logged but rate-limited
• Idempotency keys on every payment + refund call
• PCI SAQ-A self-assessment completed
• Error handling translates gateway errors to user-friendly messages
• Currency conversion logic tested with multiple currencies
• HPOS compatibility declared
• Plugin update mechanism (private update server or distribution platform)

Subscriptions support — when to add it

WooCommerce Subscriptions integration multiplies the complexity of any payment gateway. Add it only after the one-time payment flow is rock-solid in production for at least 60 days.

• Implement scheduled_subscription_payment_ hook
• Charge against saved token (not the original payment method)
• Handle subscription failures with retry logic and customer notifications
• Support customer self-service updates to payment method (key dropoff point)
• Test renewal in sandbox 24+ hours after the initial sub purchase

WooCommerce Cart/Checkout Blocks integration

WooCommerce 8.x+ defaults to the React-based Cart and Checkout Blocks (replacing the legacy shortcode checkout). Custom payment gateways must register Block-compatible payment methods — otherwise they show only on the legacy checkout, not the new one.

Pattern: register your Block payment method via woocommerce_blocks_payment_method_type_registration, ship a JS bundle that registers the method client-side, and provide a server-side equivalent. The Cart/Checkout Blocks integration is the area where most existing gateway plugins are still incomplete in 2026 — building yours with it from day one is a strong differentiator.

Logging and observability

Payment-gateway plugins fail in production at the worst times. Good logging makes debugging tractable; bad logging means hours of guessing.

• Log every API request and response (sanitized — strip card numbers, security codes)
• Log every webhook with full payload
• Tag log entries with order ID + payment intent ID for correlation
• Use WC_Logger (the WooCommerce logging facade) — admin can view logs in WC → Status → Logs
• For high-volume stores, ship logs to an external service (Loggly, Datadog, Papertrail) with a 30-day retention
• Surface failed-payment counts on the gateway settings page so admin notices spikes

Distribution model for custom gateway plugins

Custom payment-gateway plugins are typically distributed in one of three models:

• Single-client — gateway built for one client’s store. Distributed via Git, no licensing. Simplest path.
• Multi-client (paid plugin) — sold via Easy Digital Downloads + Software Licensing or Freemius. License key checks on activation. Most flexible monetization.
• WooCommerce.com Marketplace — public listing. Strict review, intensive PCI compliance check, 50% revenue share. Best discoverability if the gateway has broad appeal.

Architecture — FAQs

Should I extend WC_Payment_Gateway or WC_Payment_Gateway_CC?

WC_Payment_Gateway for one-time payments without saved cards. WC_Payment_Gateway_CC for credit-card gateways supporting saved cards. WC_Payment_Gateway with custom token logic for non-card gateways with stored payment methods (e.g., bank accounts).

How do I keep my plugin out of PCI scope?

Use the gateway’s tokenization SDK on the client (Stripe Elements, Adyen Web Components). Card data never touches your server. Your code only handles tokens. PCI scope stays at SAQ-A — minimum audit burden.

Do I need to support 3D Secure / SCA?

Yes for European buyers (SCA is mandatory). Even outside EU, 3DS reduces fraud chargebacks. Implement via the gateway’s redirect or Payment Intent flow. Test thoroughly — this is where most custom gateways have bugs.

Production — FAQs

How do I test a WooCommerce payment gateway plugin without real money?

Every gateway provides a sandbox/test mode with test card numbers. Set test API keys in your plugin’s settings, run end-to-end orders, validate the webhook flow with a tunnel like ngrok or smee.io. Never test in production with real cards.

How fast should webhook responses be?

Under 5 seconds. Most gateways retry after 5–15 seconds if no response, which causes duplicate processing. Either process synchronously and return fast, or accept-and-queue for async processing. Slow webhooks are the #1 cause of duplicate orders.

How do I distribute a custom WooCommerce payment gateway plugin?

For client-specific gateways, ship as a private plugin with a self-hosted update server. For multi-tenant SaaS-style gateways, EDD Software Licensing or Freemius. WooCommerce.com Marketplace requires their PCI review which is intensive — only for serious commercial gateways. See my WooCommerce plugin development service for licensed gateway builds.