Custom WooCommerce Payment Gateway on Block Theme

How to Integrate a Custom WooCommerce Payment Gateway in a Block Theme?

WooCommerce continues to evolve, and with the rise of Full Site Editing (FSE) and Block Themes, developers need to ensure their custom payment gateways are fully compatible with both Classic and Block-based checkout experiences.

In this guide, we’ll walk through the key steps to create and integrate a custom WooCommerce payment gateway that works seamlessly in a Block theme environment, including support for WooCommerce’s Cart and Checkout blocks.

---

🛠️ Prerequisites

• A WordPress installation with a Block-compatible theme (e.g., Twenty Twenty-Four).
• WooCommerce installed and activated.
• Basic familiarity with PHP and JavaScript.

---

1. Create the Custom Gateway Class

First, register your gateway by extending WC_Payment_Gateway. Place your gateway code inside a plugin or theme’s functions.php for testing.

class WC_Gateway_MyCustom extends WC_Payment_Gateway {

    public function __construct() {
        $this->id = 'mycustom';
        $this->method_title = 'My Custom Gateway';
        $this->method_description = 'Pay using My Custom Gateway';
        $this->has_fields = false;

        $this->init_form_fields();
        $this->init_settings();

        $this->title = $this->get_option('title');
        $this->enabled = $this->get_option('enabled');

        add_action('woocommerce_update_options_payment_gateways_' . $this->id, [$this, 'process_admin_options']);
    }

    public function init_form_fields() {
        $this->form_fields = [
            'enabled' => [
                'title' => 'Enable/Disable',
                'type'  => 'checkbox',
                'label' => 'Enable My Custom Gateway',
                'default' => 'yes',
            ],
            'title' => [
                'title' => 'Title',
                'type'  => 'text',
                'default' => 'My Custom Payment',
            ],
        ];
    }

    public function process_payment($order_id) {
        $order = wc_get_order($order_id);

        // Mark as paid for demo purposes
        $order->payment_complete();
        $order->add_order_note('Payment completed using My Custom Gateway.');

        return [
            'result' => 'success',
            'redirect' => $this->get_return_url($order),
        ];
    }
}

Then register the gateway:

add_filter('woocommerce_payment_gateways', function($gateways) {
    $gateways[] = 'WC_Gateway_MyCustom';
    return $gateways;
});

---

2. Make It Block Checkout Compatible

To work with WooCommerce Blocks (used in Block themes), your gateway needs to support the woocommerce_blocks_payment_method_type interface.

Step 1: Register Gateway Integration

Create a class that extends AbstractPaymentMethodType.

use Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType;

final class WC_Gateway_MyCustom_Blocks extends AbstractPaymentMethodType {

    protected $name = 'mycustom';

    public function initialize() {
        $settings = get_option('woocommerce_mycustom_settings', []);
        $this->settings = $settings;
    }

    public function is_active() {
        return ! empty($this->settings['enabled']) && 'yes' === $this->settings['enabled'];
    }

    public function get_payment_method_script_handles() {
        $script_url = plugin_dir_url(__FILE__) . 'build/frontend.js';

        wp_register_script(
            'wc-mycustom-blocks',
            $script_url,
            ['wp-element', 'wp-i18n', 'wp-hooks', 'wc-blocks-registry', 'wc-settings'],
            '1.0',
            true
        );

        return [ 'wc-mycustom-blocks' ];
    }

    public function get_payment_method_data() {
        return [
            'title'       => $this->settings['title'] ?? 'My Custom Payment',
            'description' => 'Pay securely using My Custom Payment Gateway.',
            'supports'    => [ 'refunds' ],
        ];
    }
}

Then register the integration with WooCommerce Blocks:

add_action(
    'woocommerce_blocks_payment_method_type_registration',
    function( Automattic\WooCommerce\Blocks\Payments\PaymentMethodRegistry $payment_method_registry ) {
        $payment_method_registry->register( new WC_Gateway_MyCustom_Blocks() );
    }
);

---

3. Add JavaScript for Checkout Block UI

You can add interactivity or branding using a simple JS entry point like frontend.js.

// frontend.js
const { registerPaymentMethod } = window.wc.blocks.registry;

registerPaymentMethod({
    name: 'mycustom',
    label: 'My Custom Payment',
    content: <p>Pay using My Custom Gateway. Fast and secure.</p>,
    canMakePayment: () => true,
    ariaLabel: 'My Custom Payment Gateway',
    supports: {
        features: ['products'],
    },
});

Bundle it with a tool like Webpack or use ESBuild if you prefer.

---

4. Test in a Block Theme

Activate a Block theme and ensure you’re using the WooCommerce Cart & Checkout blocks.

• Go to Pages > Checkout.
• Insert the Checkout block if it isn’t already.
• Try placing an order with your custom gateway.

It should appear like any other payment method.

---

✅ Bonus Tips

• Use wp_localize_script() to pass PHP values to JS.
• Support payment_complete() and payment_failed() status transitions.
• Consider adding webhook support if your gateway uses async confirmation.

---

Final Thoughts

Supporting WooCommerce’s Block checkout requires just a bit more setup than traditional gateways, but it’s the future-proof way to integrate payments on modern WordPress sites. Once your custom gateway supports the AbstractPaymentMethodType and registers its scripts correctly, you’re fully Block-compatible.

I recently worked with SMEPay for WooCommerce. You can review the code.

Keep your payment integration clean, test across themes, and your gateway will be a reliable option in any WooCommerce-powered store using Block themes.