wc-checkout-block-payment-method

WooCommerce Checkout Block payment methods

A Checkout Block integration is an adapter around a payment gateway, not a replacement for it. Implement and test each layer deliberately.

Keep the four layers separate

Layer	Responsibility
WC_Payment_Gateway	Settings, availability, validation, server-side provider calls, refunds, and classic checkout
AbstractPaymentMethodType	Registers Block assets and exposes non-secret settings to JavaScript
registerPaymentMethod()	Renders the Block UI, reports availability, prepares opaque payment data, and handles client SDK events
Store API processing	Bridges payment_data to process_payment() or an explicit PaymentContext/PaymentResult handler

Store API payment requirements only filter eligible methods. They do not register a payment UI or process money.

Use one stable identifier

Make these values equal unless a verified compatibility requirement says otherwise:

WC_Payment_Gateway::$id
AbstractPaymentMethodType::$name
registerPaymentMethod({ name })
registerPaymentMethod({ paymentMethodId })

paymentMethodId is what Checkout sends as payment_method and uses to find the PHP gateway. It defaults to name; set it explicitly if the client registration name differs. A provider payment-method type, wallet type, and Woo gateway ID are different identifiers and must not be conflated.

Register the PHP Blocks adapter

Register after woocommerce_blocks_loaded and guard the Blocks class:

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

final class MyPlugin_Blocks_Payment_Method extends AbstractPaymentMethodType {
    protected $name = 'myplugin_gateway';

    public function initialize(): void {
        $this->settings = get_option( 'woocommerce_myplugin_gateway_settings', array() );
    }

    public function is_active(): bool {
        return 'yes' === $this->get_setting( 'enabled', 'no' );
    }

    public function get_payment_method_script_handles(): array {
        $asset = file_exists( MYPLUGIN_PATH . 'build/checkout.asset.php' )
            ? require MYPLUGIN_PATH . 'build/checkout.asset.php'
            : array(
                'dependencies' => array( 'wc-blocks-registry', 'wc-settings', 'wp-element', 'wp-html-entities' ),
                'version'      => MYPLUGIN_VERSION,
            );

        wp_register_script(
            'myplugin-checkout-block',
            MYPLUGIN_URL . 'build/checkout.js',
            $asset['dependencies'],
            $asset['version'],
            true
        );
        wp_set_script_translations( 'myplugin-checkout-block', 'myplugin' );

        return array( 'myplugin-checkout-block' );
    }

    public function get_payment_method_data(): array {
        return array(
            'title'       => $this->get_setting( 'title', __( 'Pay securely', 'myplugin' ) ),
            'description' => $this->get_setting( 'description', '' ),
            'supports'    => $this->get_supported_features(),
        );
    }
}

add_action( 'woocommerce_blocks_loaded', static function (): void {
    if ( ! class_exists( AbstractPaymentMethodType::class ) ) {
        return;
    }

    add_action(
        'woocommerce_blocks_payment_method_type_registration',
        static function ( PaymentMethodRegistry $registry ): void {
            $registry->register( new MyPlugin_Blocks_Payment_Method() );
        }
    );
} );