🧩 How to Make Your Custom WooCommerce Payment Gateway Compatible with Block Checkout

As WooCommerce pushes toward a full-site block editor experience, older payment gateways built for classic checkout will no longer appear by default on the new Cart and Checkout Blocks. Such was the case with the default plugin provided by Wipay, a payment processor in the Caribbean. This made us remake their plugin – WiPay by Hexakode, this guide will show you howwe made it block-compatible — step by step.

🔗 View the full plugin code on GitHub

🧩 1. Declare Compatibility with Block Checkout

Inside your plugin’s main file (wipay-by-hexakode.php), declare support for WooCommerce Blocks and HPOS:

add_action('before_woocommerce_init', function() {
    if ( class_exists('\Automattic\WooCommerce\Utilities\FeaturesUtil') ) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility('cart_checkout_blocks', __FILE__, true);
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility('custom_order_tables', __FILE__, true);
    }
});

This ensures your gateway shows up in the block-based checkout UI.

⚙️ 2. The Payment Gateway Class

Your WC_Gateway_Wipay class should extend WC_Payment_Gateway like so:

class WC_Gateway_Wipay extends WC_Payment_Gateway {
    public function __construct() {
        $this->id = 'wipay_by_hexakode';
        $this->method_title = __( 'WiPay by Hexakode', 'wipay-pay-woo' );
        $this->supports = [ 'products', 'subscriptions', 'default', 'virtual' ];
        // ... init_form_fields, settings, etc.

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

    public function process_payment($order_id) {
        $order = wc_get_order($order_id);
        $redirect_url = $this->create_wipay_payment_redirect_url($order);
        return $redirect_url ? ['result' => 'success', 'redirect' => $redirect_url] : ['result' => 'failure'];
    }
}

This handles the server-side logic. But for blocks, we need more…

🧠 3. Register Your Gateway for WooCommerce Blocks

We register our custom block integration via WC_Wipay_Blocks in class-wipay-blocks.php.

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

final class WC_Wipay_Blocks extends AbstractPaymentMethodType {
    protected $name = 'wipay_by_hexakode';

    public function initialize() {
        $this->gateway = WC()->payment_gateways()->payment_gateways()['wipay_by_hexakode'] ?? null;
    }

    public function is_active() {
        return $this->gateway && $this->gateway->is_available();
    }

    public function get_payment_method_script_handles() {
        wp_enqueue_script(
            'wc-wipay-blocks-integration',
            plugins_url('block/wipay-blockv2.js', __DIR__),
            ['wc-blocks-registry', 'wc-settings', 'wp-element', 'wp-i18n'],
            null,
            true
        );

        wp_add_inline_script('wc-wipay-blocks-integration', 'window.wc = window.wc || {}; window.wc.wcSettings = window.wc.wcSettings || {}; window.wc.wcSettings["wipay_by_hexakode_data"] = ' . wp_json_encode([
            'title' => 'WiPay',
            'description' => 'Pay securely using WiPay.',
            'ariaLabel' => 'WiPay',
        ]) . ';', 'before');

        return ['wc-wipay-blocks-integration'];
    }

    public function get_payment_method_data() {
        return [
            'title' => 'WiPay',
            'description' => 'Pay securely using WiPay.',
            'ariaLabel' => 'WiPay',
            'supports' => [ 'products', 'subscriptions', 'default', 'virtual' ]
        ];
    }
}

And register it like this in your main plugin file:

add_action('woocommerce_blocks_loaded', function () {
    add_action('woocommerce_blocks_payment_method_type_registration', function ($registry) {
        $registry->register(new WC_Wipay_Blocks());
    });
});

🧱 4. Create the JavaScript for the Block Checkout

Your file block/wipay-blockv2.js should register the payment method like so:

document.addEventListener("DOMContentLoaded", function () {
  const settings = window.wc?.wcSettings?.["wipay_by_hexakode_data"] || {};
  const { createElement } = window.wp.element;

  window.wc.wcBlocksRegistry.registerPaymentMethod({
    name: "wipay_by_hexakode",
    label: createElement("span", null, settings.title || "WiPay"),
    ariaLabel: settings.ariaLabel || "WiPay",
    supports: { features: ["products", "subscriptions", "default", "virtual"] },
    canMakePayment: () => Promise.resolve(true),
    content: createElement("p", null, settings.description || "Pay with WiPay"),
    edit: createElement("p", null, settings.description || "Pay with WiPay"),
    save: null,
  });

  console.log("[WiPay] registered in block checkout");
});

✅ Now, when a user visits the Checkout Block, they’ll see WiPay as an option.

✅ Final Result

Once integrated:

• Your payment method will show in both classic and block checkouts.
• It will include a working redirect/payment flow.
• It supports subscriptions and virtual products.
• Works seamlessly with WooCommerce HPOS (High-Performance Order Storage).

📦 Files Used

• wipay-by-hexakode.php – main plugin file
• class-wc-gateway-wipay.php – server-side gateway logic
• class-wipay-blocks.php – WooCommerce Blocks integration
• block/wipay-blockv2.js – JS registration for the payment method block

📥 Get the Full Code

👉 GitHub Repository: hexakodeagency/wipay-block-checkout-plugin
Includes everything — PHP classes, JS logic, settings panel, and admin UX.

---

Need help making your own gateway block-ready or want to fork this for another payment processor? Let me know — we can build it right.