How to Add Custom Payment Gateways to WooCommerce for Region-Specific Checkout
How to add a custom payment gateway to WooCommerce for regional checkout: WC_Payment_Gateway, process_payment, webhooks, country and currency rules, Checkout block support and PCI scope, checked 15 November 2026.

To add a custom payment gateway to WooCommerce, you write a small plugin with a class that extends WC_Payment_Gateway, register it on the woocommerce_payment_gateways filter, return a result array from process_payment(), and add a separate payment method integration so the gateway also shows up in the Checkout block. For a regional checkout you add one more layer: rules that decide which customers see the method, by billing country and by currency. We checked every API named below against the WooCommerce developer documentation and the WooCommerce source on 15 November 2026, when the latest stable release on GitHub was 11.3.0.
This guide is for developers and the people who hire them. We cover what a gateway actually has to do, a working example for a redirect-style regional gateway, how the Checkout block changes the picture, which PCI questionnaire you land on, how to handle webhooks and duplicate orders, and the mistakes other developers keep reporting. If you only want a ready-made plugin for iDEAL, UPI or SEPA, read our list of WooCommerce payment gateway plugins instead. We do not repeat that list here.
What is a custom payment gateway in WooCommerce?
A custom payment gateway is a PHP class that WooCommerce treats like any bundled payment method. It has an ID, a title, a settings screen, a test for “can this customer use me right now”, and a method that takes the order and starts the payment. The WooCommerce Payment Gateway API page groups gateways into four kinds: form based (the customer is redirected to the provider’s page), iframe based, direct (the card or account fields sit on your checkout page), and offline (cheque or bank transfer, where no online payment happens).
Most regional gateways are the first kind. The shopper picks a local method, WooCommerce creates the order, your code asks the provider for a hosted payment page, and the shopper pays there. The provider later tells your site the result. That shape keeps card numbers and bank credentials off your server, which matters for the PCI section below.
Should you build a gateway or install one?
Build only when no existing plugin covers your method, your provider, or your rules. Local-method providers usually ship their own WooCommerce plugin, and those plugins carry years of edge cases you would otherwise rediscover. The numbers below come from the WordPress.org plugin API on 15 November 2026.
Provider plugin | Active installs | Rating on WordPress.org | Last updated |
|---|---|---|---|
Mollie Payments for WooCommerce 8.2.0 | 100,000+ | About 3.6 of 5, from 69 ratings | 13 November 2026 |
Razorpay for WooCommerce 4.8.9 | 100,000+ | About 2.5 of 5, from 23 ratings | 4 November 2026 |
Paytm Payment Gateway 2.8.9 | 3,000+ | About 3.1 of 5, from 15 ratings | 23 September 2026 |
Mollie’s own docs list methods such as iDEAL, Bancontact, BLIK, EPS, Przelewy24, TWINT and SEPA Direct Debit on one page, and tell you to read each method’s page for country, currency and amount limits. That is the pattern to expect from any regional provider: the method list is long and the rules are per method. Read Mollie’s payment methods overview for an example.
Your situation | What we would do |
|---|---|
Your provider has a maintained WooCommerce plugin that supports the Checkout block | Install it. Spend your time on configuration and testing. |
The provider only has an API and no plugin | Build a redirect-style gateway like the one below. |
You need one extra rule on top of an existing gateway (hide it for some countries, add a fee) | Do not fork it. Use the |
You need to take card numbers on your own page | Stop and read the PCI section first. Use the provider’s hosted fields instead. |
The method is an offline one (bank transfer, pay at pickup) | Extend |
How do you add a custom payment gateway to WooCommerce?
Put the gateway in its own plugin, not in a theme’s functions.php. The Payment Gateway API page says to build it as a standalone plugin, create the class on plugins_loaded, and register it by filtering woocommerce_payment_gateways. Declare compatibility with High-Performance Order Storage and the Cart and Checkout blocks in the same file, so the merchant does not see a warning on the Features screen. Our HPOS migration guide explains why every order read and write in a gateway should go through the order object.
Checked on 15 November 2026 against the WooCommerce developer docs. The plugin is called wcd-regional-gateway, and every provider URL in it is a placeholder.
<?php
/**
* Plugin Name: WCD Regional Gateway (example)
* Requires Plugins: woocommerce
*/
defined( 'ABSPATH' ) || exit;
add_action( 'before_woocommerce_init', function () {
if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'cart_checkout_blocks', __FILE__, true );
}
} );
add_action( 'plugins_loaded', function () {
if ( ! class_exists( 'WC_Payment_Gateway' ) ) {
return;
}
require_once __DIR__ . '/class-wcd-regional-gateway.php';
add_filter( 'woocommerce_payment_gateways', function ( $gateways ) {
$gateways[] = 'WCD_Regional_Gateway';
return $gateways;
} );
} );
// Checkout block: the class file is loaded only when the registry asks for it.
add_action( 'woocommerce_blocks_payment_method_type_registration', function ( $registry ) {
require_once __DIR__ . '/class-wcd-regional-blocks.php';
$registry->register( new WCD_Regional_Blocks() );
} );What does WC_Payment_Gateway give you?
The base class does more than the docs page lists, so we read the source. A gateway inherits the enabled, title and description properties, the supports list (it defaults to array( 'products' )), a max_amount property, get_return_url(), process_admin_options() for the settings screen, and token helpers for saved methods. The base process_payment() returns an empty array and the base process_refund() returns false, so you must override both for a working gateway.
The default is_available() is short. It checks that the gateway is enabled and, when a cart exists, that the total does not exceed max_amount. The countries and availability properties are declared in the class but nothing in that file reads them. If you want a country rule, you write it yourself. That is the single most useful thing to know before building a regional gateway.
Part | What you set or override | Notes |
|---|---|---|
|
| Call |
| The | Enable checkbox, title, description, plus your own keys. |
| Your region and currency rules | Call the parent first, then add yours. |
| Start the payment, return | Return |
| Call the provider’s refund API | Return |
| Fields on the classic checkout | Only needed when |
How do you limit a gateway to one region or currency?
Override is_available(). Keep the parent call, then compare the customer’s billing country and the store currency against two settings the merchant controls. Decide up front whether you key on billing or shipping country. We use billing, because that is what most local providers validate, and we say so on the settings screen.
<?php
class WCD_Regional_Gateway extends WC_Payment_Gateway {
public function __construct() {
$this->id = 'wcd_regional';
$this->method_title = 'Regional Pay (example)';
$this->method_description = 'Hosted-page payments for selected countries and currencies.';
$this->has_fields = false; // redirect flow: nothing to collect on the checkout page
$this->supports = array( 'products', 'refunds' );
$this->init_form_fields();
$this->init_settings();
$this->title = $this->get_option( 'title' );
$this->description = $this->get_option( 'description' );
add_action( 'woocommerce_update_options_payment_gateways_' . $this->id, array( $this, 'process_admin_options' ) );
add_action( 'woocommerce_api_wcd_regional', array( $this, 'handle_webhook' ) );
}
public function init_form_fields() {
$this->form_fields = array(
'enabled' => array( 'title' => 'Enable', 'type' => 'checkbox', 'label' => 'Enable Regional Pay', 'default' => 'no' ),
'title' => array( 'title' => 'Title', 'type' => 'text', 'default' => 'Pay with Regional Pay' ),
'description' => array( 'title' => 'Description', 'type' => 'textarea', 'default' => 'You will be sent to a secure page to pay.' ),
'countries' => array( 'title' => 'Billing countries', 'type' => 'multiselect', 'class' => 'wc-enhanced-select', 'options' => WC()->countries->get_countries(), 'description' => 'Leave empty for all countries.' ),
'currencies' => array( 'title' => 'Currencies', 'type' => 'text', 'description' => 'Comma separated, for example EUR,PLN. Leave empty for all.' ),
'api_key' => array( 'title' => 'API key', 'type' => 'password' ),
'webhook_secret' => array( 'title' => 'Webhook secret', 'type' => 'password' ),
);
}
public function is_available() {
if ( ! parent::is_available() ) {
return false;
}
if ( ! WC()->customer ) {
return true; // admin screens, REST requests without a customer
}
$countries = (array) $this->get_option( 'countries', array() );
if ( $countries && ! in_array( WC()->customer->get_billing_country(), $countries, true ) ) {
return false;
}
$currencies = array_filter( array_map( 'trim', explode( ',', strtoupper( (string) $this->get_option( 'currencies' ) ) ) ) );
return ! $currencies || in_array( get_woocommerce_currency(), $currencies, true );
}Two details matter here. First, WooCommerce builds the admin list from method_title and method_description, and falls back to the customer-facing title when they are empty, so set both. Second, the server rule is the real rule. In the Checkout block you can also hide the method early with canMakePayment, which receives the billing address, but the Store API checks the chosen method against the available gateways again at order time. In the source, a method that is not available for the order returns a woocommerce_rest_checkout_payment_method_disabled error with HTTP status 400. Never rely on the JavaScript check alone.
What about currency and amounts?
Regional providers want amounts in the currency’s smallest unit. Stripe’s currency page is a clear reference: 1000 charges 10 USD, and 10 charges 10 JPY because yen has no minor unit. Some currencies have three decimals, and a few have special rules, such as Icelandic krona being charged as a two-decimal value that always ends in 00. Do not use the store’s “number of decimals” display setting for this. It is a presentation choice. Keep a small table of zero-decimal and three-decimal currencies from your provider’s docs, and test one of each. Providers also enforce minimum charges per currency, so a very small order can fail only in one country.
Settlement matters too. If the customer’s currency differs from the provider’s settlement currency, the provider converts, and the customer’s bank may add a foreign exchange fee. That is a business decision for the merchant. For a developer it means one thing: send the order’s own currency, never a converted figure you computed yourself. Source: Stripe’s supported currencies page, read on 15 November 2026.
How does process_payment() work for a redirect gateway?
WooCommerce calls process_payment( $order_id ) when the shopper places the order. You load the order, call the provider, save the provider’s payment ID on the order, and return either success with a redirect URL or failure with an error notice. The docs are specific about two things. Use $order->payment_complete() when money is confirmed, never update_status(), because it handles stock and picks Processing or Completed correctly. And use On-Hold when the outcome needs confirmation.
The example sends an idempotency key built from the order, so a repeated request cannot create a second payment on providers that support one. The docs recommend this directly: use the provider’s idempotency support, save the transaction ID on the order straight away, and check its status before charging again on a retry.
public function process_payment( $order_id ) {
$order = wc_get_order( $order_id );
if ( ! $order ) {
return array( 'result' => 'failure' );
}
$response = wp_remote_post( 'https://api.provider.example/v1/payments', array(
'timeout' => 20,
'headers' => array(
'Authorization' => 'Bearer ' . $this->get_option( 'api_key' ),
'Content-Type' => 'application/json',
'Idempotency-Key' => 'wc-' . $order->get_id() . '-' . $order->get_order_key(),
),
'body' => wp_json_encode( array(
'amount' => $this->to_minor_units( $order->get_total(), $order->get_currency() ),
'currency' => $order->get_currency(),
'reference' => (string) $order->get_id(),
'return_url' => $this->get_return_url( $order ),
'webhook_url' => WC()->api_request_url( 'wcd_regional' ),
) ),
) );
$body = json_decode( wp_remote_retrieve_body( $response ), true );
if ( is_wp_error( $response ) || 201 !== wp_remote_retrieve_response_code( $response ) || empty( $body['id'] ) || empty( $body['checkout_url'] ) ) {
$order->add_order_note( 'Regional Pay: the payment could not be started.' );
wc_add_notice( __( 'We could not start the payment. Please try again or choose another method.', 'wcd-regional' ), 'error' );
return array( 'result' => 'failure' );
}
$order->update_meta_data( '_wcd_payment_id', sanitize_text_field( $body['id'] ) );
$order->update_status( 'on-hold', 'Waiting for Regional Pay to confirm the payment.' ); // saves the order
WC()->cart->empty_cart();
return array(
'result' => 'success',
'redirect' => esc_url_raw( $body['checkout_url'] ),
);
}
private function to_minor_units( $amount, $currency ) {
$zero_decimal = array( 'JPY', 'KRW', 'VND' ); // copy the real list from your provider's docs
return (int) round( (float) $amount * ( in_array( $currency, $zero_decimal, true ) ? 1 : 100 ) );
}The docs add a point about retries that is easy to miss. They describe moving an order out of Pending payment or Failed, for example to On-Hold, so that checkout stops asking for payment again, and they describe that behaviour from WooCommerce 11.4. That is newer than the 11.3.0 release we checked, so treat it as upcoming. Keep Pending payment only for short waits, because unpaid orders are cancelled after the stock hold time, which is 60 minutes by default. The process_payment(), handle_webhook() and process_refund() blocks all belong inside the same WCD_Regional_Gateway class as the constructor; the refund block closes it.
How do webhooks confirm the payment?
The shopper may close the tab before returning to your site, so the provider’s server-to-server call is the source of truth. WooCommerce’s WC-API pattern gives you a URL: build it with WC()->api_request_url( 'wcd_regional' ), then hook woocommerce_api_wcd_regional. The hook name is the lowercased value of the wc-api argument, as in the docs’ PayPal example.
A safe handler does five things in order: verify the signature on the raw body, find the order and confirm it belongs to this gateway, ignore events for orders already paid, check the amount and currency, and only then call payment_complete(). It answers with HTTP 200 quickly so the provider stops retrying. The docs also say to confirm the amount paid matches the order total before payment_complete(), and to put the order On-Hold for review when it does not.
public function handle_webhook() {
$raw = file_get_contents( 'php://input' );
$signature = isset( $_SERVER['HTTP_X_SIGNATURE'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_X_SIGNATURE'] ) ) : '';
if ( ! hash_equals( hash_hmac( 'sha256', $raw, (string) $this->get_option( 'webhook_secret' ) ), $signature ) ) {
status_header( 401 );
exit;
}
$event = json_decode( $raw, true );
$order = ! empty( $event['reference'] ) ? wc_get_order( absint( $event['reference'] ) ) : false;
// Unknown order, another gateway's order, or a payment id we did not issue: acknowledge and stop.
if ( ! $order || $order->get_payment_method() !== $this->id || $order->get_meta( '_wcd_payment_id' ) !== ( $event['payment_id'] ?? '' ) ) {
status_header( 200 );
exit;
}
if ( ! $order->is_paid() ) { // duplicate deliveries land here after the first one worked
$status = $event['status'] ?? '';
if ( 'paid' === $status ) {
$amount_ok = $this->to_minor_units( $order->get_total(), $order->get_currency() ) === (int) ( $event['amount'] ?? 0 )
&& $order->get_currency() === ( $event['currency'] ?? '' );
if ( $order->has_status( 'cancelled' ) ) {
$order->add_order_note( 'Regional Pay reported a payment for a cancelled order. Review and refund if needed.' );
} elseif ( ! $amount_ok ) {
$order->update_status( 'on-hold', 'Regional Pay amount or currency does not match the order. Check before shipping.' );
} else {
$order->payment_complete( sanitize_text_field( $event['payment_id'] ) );
}
} elseif ( 'failed' === $status ) {
$order->update_status( 'failed', 'Regional Pay reported a failed payment.' );
}
}
status_header( 200 );
exit;
}The cancelled-order branch is deliberate. As the mistakes box below explains, payment_complete() accepts cancelled orders, and a late gateway callback can then push stock below zero. A guard in your callback is cheap. Our diagnosis order for duplicate orders and failed payments covers the store-owner side of the same problems.
How do refunds work?
Add 'refunds' to supports and override process_refund( $order_id, $amount, $reason ). WooCommerce shows the refund button on the order only when the gateway supports it and the order can be refunded through it. Return true when the provider accepted the refund, a WP_Error with a readable message when it did not. Do not return false silently, because the merchant sees a generic failure and has to guess why.
public function process_refund( $order_id, $amount = null, $reason = '' ) {
$order = wc_get_order( $order_id );
$payment_id = $order ? $order->get_meta( '_wcd_payment_id' ) : '';
if ( ! $payment_id || ! $amount ) {
return new WP_Error( 'wcd_refund', 'Missing payment id or amount.' );
}
$response = wp_remote_post( 'https://api.provider.example/v1/payments/' . rawurlencode( $payment_id ) . '/refunds', array(
'timeout' => 20,
'headers' => array( 'Authorization' => 'Bearer ' . $this->get_option( 'api_key' ), 'Content-Type' => 'application/json' ),
'body' => wp_json_encode( array( 'amount' => $this->to_minor_units( $amount, $order->get_currency() ), 'reason' => $reason ) ),
) );
if ( is_wp_error( $response ) || 201 !== wp_remote_retrieve_response_code( $response ) ) {
return new WP_Error( 'wcd_refund', 'The provider did not accept the refund.' );
}
$order->add_order_note( 'Refund of ' . wc_price( $amount, array( 'currency' => $order->get_currency() ) ) . ' sent to Regional Pay.' );
return true;
}
}How do you make the gateway work in the Checkout block?
The Checkout block does not draw your gateway from PHP. A gateway needs a payment method integration with two halves: a PHP class that extends AbstractPaymentMethodType and a script that calls registerPaymentMethod. Without both, the gateway works on the classic shortcode checkout and is missing from the block. The WooCommerce developer blog says the same thing: a gateway appears in the Checkout block only when it is registered with the block system, and an unregistered gateway gets no warning anywhere.
Payment processing does not move. The integration docs state that payments are still handled through the Payment Gateway API: the block converts the payment_data sent by your script into $_POST and calls your process_payment(). So everything above keeps working. The block class below is what makes the method visible. Checked on 15 November 2026 against the payment method integration page in the WooCommerce docs.
<?php
use Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType;
final class WCD_Regional_Blocks extends AbstractPaymentMethodType {
protected $name = 'wcd_regional'; // must match the gateway id and the JS name
public function initialize() {
$this->settings = get_option( 'woocommerce_wcd_regional_settings', array() ); // runs on every request: keep it cheap
}
public function is_active() {
return filter_var( $this->get_setting( 'enabled', false ), FILTER_VALIDATE_BOOLEAN );
}
public function get_payment_method_script_handles() {
wp_register_script(
'wcd-regional-blocks',
plugins_url( 'blocks.js', __FILE__ ),
array( 'wc-blocks-registry', 'wc-settings', 'wp-element', 'wp-html-entities' ),
'1.0.0',
true
);
return array( 'wcd-regional-blocks' );
}
public function get_payment_method_data() {
return array(
'title' => $this->get_setting( 'title' ),
'description' => $this->get_setting( 'description' ),
'supports' => $this->get_supported_features(),
);
}
}The script below needs no build step. It reads the data the PHP class exposes through wc.wcSettings.getSetting( 'wcd_regional_data' ) and registers the method. Use a build step with the WooCommerce dependency extraction plugin when your UI grows past a label and a sentence. The docs warn against installing @woocommerce/blocks-registry from npm.
( function () {
const { registerPaymentMethod } = window.wc.wcBlocksRegistry;
const { getSetting } = window.wc.wcSettings;
const { createElement } = window.wp.element;
const { decodeEntities } = window.wp.htmlEntities;
const settings = getSetting( 'wcd_regional_data', {} );
const title = decodeEntities( settings.title || 'Regional Pay' );
const description = createElement( 'div', null, decodeEntities( settings.description || '' ) );
registerPaymentMethod( {
name: 'wcd_regional',
paymentMethodId: 'wcd_regional',
label: createElement( 'span', null, title ),
ariaLabel: title,
content: description,
edit: description,
canMakePayment: () => true, // the server-side is_available() still decides
supports: { features: settings.supports || [ 'products' ] },
} );
} )();Which hook should process the payment?
For most gateways, nothing changes: process_payment() runs. The docs describe an alternative for advanced cases, the action woocommerce_rest_checkout_process_payment_with_context, which receives a PaymentContext and a PaymentResult and is described as the preferred place to hook payment processing in the Store API. If a callback sets a status on the result object, legacy processing is skipped for your method. Use it when you need more context than $_POST gives you. Our Checkout block migration guide and Store API developer guide cover the surrounding pieces.
If your method has fields on the page, such as a phone number for a mobile wallet, they live in the content component and travel to the server through onPaymentSetup and paymentMethodData. In the classic checkout the same job belongs to payment_fields(). Keep both in step, because one gateway can run in both checkouts on different pages of the same store.
Which PCI DSS SAQ applies to a custom checkout that posts to a gateway?
It depends on who builds the page that collects the payment details. The PCI Security Standards Council’s FAQ gives the clearest answer. When the processor hosts the page, through a redirect or an iframe, every page element comes only from a validated third party and SAQ A applies. When your site builds the payment page and posts the data straight to the processor (direct post), page elements come from your site as well, and SAQ A-EP applies.
Integration style | Where card or bank data is entered | SAQ in the PCI SSC FAQ |
|---|---|---|
Redirect to the provider’s page | On the provider’s site | SAQ A |
Provider iframe embedded in your page | On the provider’s page inside your page | SAQ A, with an extra script-attack criterion |
Direct post from a form you build | On your page, sent to the provider | SAQ A-EP |
Card data reaches your server | On your server | Not covered by either. Ask your acquirer, and expect a much larger assessment. |
The iframe row changed with PCI DSS 4.0.1. PCI SSC FAQ 1588 (February 2025) says the SAQ A script criterion applies to merchants who embed a processor’s payment form or page, such as through an iframe. The merchant must confirm the page is not susceptible to attacks from scripts, either by applying script protections like those in requirements 6.4.3 and 11.6.1, or by getting written confirmation from a compliant provider that its embedded solution, implemented as instructed, protects the page. The criterion does not apply to merchants who redirect customers to the provider’s site. That is one more reason our example is a redirect gateway. Sources: PCI SSC FAQ on direct post versus iframe and PCI SSC FAQ on the SAQ A script criterion, both read on 15 November 2026.
We are not your assessor. Your acquirer or payment brand decides which questionnaire you file, and the FAQ itself tells merchants to confirm with them. What we can say as developers: the less your pages touch payment data, the shorter the conversation.
Which checks catch a gateway bug before customers do?
Test the unhappy paths, because the happy path always works in a demo. Use the provider’s sandbox keys and walk through this list on both the classic and the Checkout block page, at desktop width and at a 390 pixel phone width.
- Pay successfully, then confirm the order moves from On-Hold to Processing only after the webhook, not on the return page.
- Close the provider tab and pay later, then confirm the webhook still completes the order.
- Send the same webhook twice and confirm there is one note and no second stock reduction.
- Change the billing country to one outside your list and confirm the method disappears, then try forcing it through a stale tab and confirm the checkout refuses it.
- Pay with a zero-decimal currency and a two-decimal one and compare the provider’s amount to the order total.
- Refund part of an order and confirm the order note and the provider’s dashboard agree.
- Cancel an unpaid order, then send a paid webhook for it, and confirm the cancelled-order branch fires.
- Run the whole flow with HPOS on, so you know every order read and write goes through the order object.
Repeat this list after each WooCommerce update. For card gateways, the provider’s test card numbers are in its docs. For regional methods, ask for sandbox accounts early, because some local schemes need a business verification step before they give you test credentials.
Common mistakes people report
Reports we checked on 15 November 2026. These come from the WooCommerce GitHub tracker and the WooCommerce developer documentation. We paraphrase and link each one, and several issues were still open when we looked, so read the original to see whether it has since been fixed.
- The gateway works on the old checkout and vanishes in the block. The WooCommerce developer blog says a gateway shows in the Checkout block only when it is registered through the block system, with a PHP class and a
registerPaymentMethodcall. Developers who skip that step see no error. WooCommerce developer blog. - Duplicate orders from several well-known gateways. A store owner reported in October 2026 that a small share of orders paid through Stripe, Klarna and PayPal plugins produced two or three orders within minutes, on HPOS with the classic checkout, and could not reproduce it by double-clicking. The report asks for a core safeguard. Until one exists, your gateway should use idempotency keys and check order status before charging. woocommerce issue 69865.
- A late payment takes stock below zero. A report from October 2026 describes an offsite payment that arrives after the stock hold expired, or after the order was cancelled as unpaid.
payment_complete()accepts cancelled orders and reduces stock again, and a fix at the checkout does not stop a gateway callback. Guard the status in your own webhook handler. woocommerce issue 70018. - Two checkout requests fire at once. A September 2026 report found that putting both the Cart block and the Checkout block on one page can send two parallel checkout requests when the shopper presses Place Order, and a saved token or cash on delivery can then create double orders. Test the page layout the merchant really uses. woocommerce issue 68693.
- No per-gateway checkout fields yet. A feature request still open in September 2026 asks for gateways to hide or relax checkout fields, for example a pay-at-location method that does not need a full address. Today the required and hidden fields are set once on the server with the country locale filter and applied on page load, so a regional gateway cannot slim the form by itself. Do not promise that to a client. woocommerce issue 61007.
- Hooks in the gateway class never fire. The Payment Gateway API page notes that gateway classes load only when needed, such as at checkout or on the settings page, so hooks that must always run belong outside the class, or behind a WC-API callback. Payment Gateway API docs.
What do we suggest?
Install the provider’s plugin when one exists and it supports the Checkout block. Build a gateway only for a provider without one, or for a method with rules no plugin covers. When you build, choose the redirect flow first: it is the shortest code, the lightest PCI scope and the easiest to test. Add the block integration on day one rather than later, because the shopper-facing checkout on new stores is increasingly the block version.
Our own position is plain: we write custom gateways for stores that need them, and we say no when a maintained plugin does the job. If you are weighing it for a project, tell us the provider, the countries and the currencies, and we will say whether to build or install.
Frequently asked questions
Can one gateway class handle several currencies?
Yes. Check get_woocommerce_currency() in is_available() if the gateway only supports some currencies, and send the order’s own currency to the provider. Do not convert amounts yourself unless the provider asks you to.
Can I add the gateway in functions.php?
It works, but the docs recommend a standalone plugin, and a theme change would take your payment method away. Use a plugin with Requires Plugins: woocommerce in its header.
Do I need to declare HPOS and block compatibility?
Declare both with FeaturesUtil::declare_compatibility() on before_woocommerce_init, and then make the claim true: use order object methods for every read and write, and register the block integration.
Where should the API key live?
A settings field is simple, but it is stored in the options table. For a site you control, define the key as a constant in wp-config.php and read it in the gateway, with the settings field as a fallback. Never print it back into the settings form.
How do I test without real money?
Use the provider’s sandbox credentials and its test payment methods. Keep the sandbox and live webhook secrets in separate settings so a copied database cannot confirm real orders from a test event.
Where should you go next?
Read the Payment Gateway API page and the payment method integration page for the current text, since both change with releases. Then run the checks above on a staging copy. Our payment gateway plugin comparison is the better starting point if you would rather install than build. Facts and code in this guide were checked against the docs and source on 15 November 2026, not run on a live store, so test your own version before you ship it.
Plugins we build and run
We maintain these ourselves, which is why we can support them on your site.
- BuddyNextThe self-hosted community engine for WordPress
- BuddyXFree community theme, Pro when you outgrow it
- ReignPremium community theme. Add pieces, build anything
- JetonomyCommunity forum and Q&A for WordPress
- EventonomyEvents and RSVPs for WordPress communities
- LearnomyCourses and learning communities on WordPress
- ListoraDirectories and listings your members can browse
- SnipShareCode sharing built for developer communities
- WB Ad ManagerAd placements that turn traffic into revenue
- WP Career BoardA job board your community actually uses
- WP Sell ServicesSell services with offers, orders, and payouts
- MediaVersePhotos, video, and media albums for members
- WB GamificationPoints, badges, and rewards that keep members active
- Product RoadmapPublic roadmaps with voting your users trust



