woocommerce-payments

📁 peixotorms/odinlayer-skills 📅 4 days ago

总安装量

周安装量

#48845

全站排名

安装命令

npx skills add https://github.com/peixotorms/odinlayer-skills --skill woocommerce-payments

Agent 安装分布

amp 1

opencode 1

kimi-cli 1

codex 1

github-copilot 1

claude-code 1

Skill 文档

WooCommerce Payment Gateway Development

Reference for building payment gateways with classic and block checkout support.

1. Gateway Registration

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

Extend WC_Payment_Gateway and implement process_payment() and optionally process_refund().

2. Supported Features

Feature	Description
`products`	Standard product payments
`refunds`	Admin refund processing
`subscriptions`	WooCommerce Subscriptions support
`tokenization`	Saved payment methods
`pre-orders`	Pre-order charge scheduling

3. Gateway Class Structure

Key methods to implement:

Method	Purpose
`__construct()`	Set `$this->id`, `$this->supports`, call `init_form_fields()` and `init_settings()`
`init_form_fields()`	Define admin settings (enabled, title, description, API keys)
`process_payment( $order_id )`	Process payment â return `['result' => 'success', 'redirect' => $url]` or `['result' => 'failure']`
`process_refund( $order_id, $amount, $reason )`	Process refund â return `true` or `WP_Error`
`validate_fields()`	Validate checkout fields â call `wc_add_notice()` on errors, return `bool`

Payment Flow

Customer clicks "Place Order"
    â validate_fields()
    â process_payment( $order_id )
        â Call external API
        â $order->payment_complete()
        â WC()->cart->empty_cart()
        â Return redirect to thank-you page

Tokenization (Saved Cards)

Extend WC_Payment_Gateway_CC (credit cards) or WC_Payment_Gateway_eCheck for built-in tokenization UI. Add 'tokenization' to $this->supports and implement add_payment_method().

4. Block Checkout Integration

The Block Checkout (default since WooCommerce 8.3) requires separate registration from the classic WC_Payment_Gateway.

Architecture

Classic Checkout          Block Checkout
âââââââââââââââââ         âââââââââââââââââ
WC_Payment_Gateway   +    AbstractPaymentMethodType (server)
                          registerPaymentMethod()   (client JS)

Server-Side: AbstractPaymentMethodType

Method	Purpose
`initialize()`	Load settings from `get_option()`
`is_active()`	Return whether gateway is enabled
`get_payment_method_script_handles()`	Register and return JS handles
`get_payment_method_data()`	Return title, description, supports array for JS

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

Client-Side: registerPaymentMethod

const { registerPaymentMethod } = wc.wcBlocksRegistry;

registerPaymentMethod( {
    name: 'mce_gateway',
    label: 'My Gateway',
    content: React.createElement( 'div', null, 'Pay with My Gateway.' ),
    edit: React.createElement( 'div', null, '[My Gateway]' ),
    canMakePayment: () => true,
    ariaLabel: 'My Gateway',
    supports: { features: [ 'products' ] },
} );

Declare Compatibility

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

5. Common Mistakes

Mistake	Fix
Only implementing classic checkout	Register `AbstractPaymentMethodType` for block checkout too
Not declaring block checkout compatibility	Add `FeaturesUtil::declare_compatibility('cart_checkout_blocks', ...)`
Missing `validate_fields()`	Always validate before `process_payment()`
Not calling `$order->payment_complete()`	Required to trigger order status change and emails
Forgetting `WC()->cart->empty_cart()`	Cart persists after payment without this
Hard-coding currency/amount format	Use `$order->get_total()` and WC formatting functions

Related Skills

woocommerce-setup â Extension architecture, plugin headers, FeaturesUtil
woocommerce-data â Order/product CRUD, HPOS, Store API, REST API
woocommerce-hooks â Order lifecycle hooks, checkout hooks, email hooks

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台