WooCommerce Payment Gateway Development
Before writing code
Fetch live docs:
- Web-search
site:developer.woocommerce.com payment gateway api for payment gateway guide
- Web-search
woocommerce payment gateway tutorial for implementation patterns
- Fetch
https://woocommerce.github.io/code-reference/classes/WC-Payment-Gateway.html for class reference
Gateway Architecture
Base Class: WC_Payment_Gateway
All gateways extend WC_Payment_Gateway (which extends WC_Settings_API):
| Property |
Description |
$id |
Unique gateway identifier |
$method_title |
Admin-facing title |
$method_description |
Admin-facing description |
$title |
Customer-facing title |
$description |
Customer-facing description |
$icon |
URL to gateway icon |
$has_fields |
Whether gateway has payment fields on checkout |
$supports |
Array of supported features |
Registration
Filter woocommerce_payment_gateways:
add_filter( 'woocommerce_payment_gateways', function( $gateways ) {
$gateways[] = 'My_Payment_Gateway';
return $gateways;
});
Implementation Methods
Required Methods
__construct() — set $id, $method_title, $supports, call init_form_fields(), init_settings(), load saved settings, register process_admin_options hook
init_form_fields() — define admin settings (API keys, sandbox mode, etc.)
process_payment( $order_id ) — core payment logic, returns result + redirect array
Optional Methods
payment_fields() — render custom payment form HTML on checkout
validate_fields() — validate payment form input
process_refund( $order_id, $amount, $reason ) — handle refunds
get_icon() — customize the gateway icon display
process_payment Return Format
return [
'result' => 'success', // or 'failure'
'redirect' => $order->get_checkout_order_received_url(),
];
Integration Models
Direct Integration
Gateway processes payment inline:
- Collect card data via
payment_fields() (or tokenized via JS SDK)
- Call payment processor API in
process_payment()
- Mark order:
$order->payment_complete( $transaction_id )
- Return success with redirect to thank-you page
Redirect Integration
Customer redirected to external payment page:
process_payment() returns redirect URL to processor
- Processor handles payment and redirects back
- Handle return via a webhook or callback URL
- Process the response and update order status
Hosted/Iframe Integration
Payment form loaded in iframe on checkout page:
- Set
$has_fields = true
- Render iframe/JS SDK in
payment_fields()
- Handle tokenization callback
Supports Array
$this->supports = [
'products', // Basic payment support
'refunds', // process_refund()
'tokenization', // Saved payment methods
'subscriptions', // WooCommerce Subscriptions
'subscription_cancellation',
'subscription_reactivation',
'subscription_suspension',
'subscription_amount_changes',
'subscription_date_changes',
];
Tokenization (Saved Payment Methods)
WC_Payment_Token System
- Extend
WC_Payment_Token_CC (credit cards) or WC_Payment_Token (generic)
$this->supports[] = 'tokenization'
- Override
tokenization_script() to enqueue JS
- Save tokens via
WC_Payment_Tokens::set_users_default()
- Customer manages saved methods in My Account > Payment Methods
Webhook/IPN Handling
Registering Webhook Endpoints
Use WC_API to register callback URLs:
add_action( 'woocommerce_api_{$id}', [ $this, 'handle_webhook' ] )
- Callback URL:
home_url( '/wc-api/{$id}/' )
- Verify signatures, process payment notifications, update order status
Order Status Management
$order->update_status( 'processing', 'Payment received' ) — status + note
$order->payment_complete( $transaction_id ) — marks paid, triggers emails
$order->update_status( 'failed', 'Payment failed' ) — mark failed
$order->add_order_note( 'Note text' ) — add admin/customer note
Block Checkout Support
For block-based checkout, gateways need a JS integration:
- Register a payment method via
@woocommerce/blocks-registry → registerPaymentMethod()
- Provide React components for:
content, edit, label
- Define
canMakePayment callback
- Handle payment data submission via
onPaymentSetup event
Best Practices
- Never log or store raw credit card data
- Always use sandbox/test mode for development
- Verify webhook signatures to prevent spoofing
- Handle all error states gracefully with clear customer messages
- Support refunds if the processor allows them
- Declare
cart_checkout_blocks compatibility and provide block checkout integration
- Use
$order->payment_complete() — it handles status, stock reduction, and email triggers
- Store transaction IDs via
$order->set_transaction_id()
Fetch the WooCommerce payment gateway documentation and code reference for exact method signatures, supported features, and block checkout integration patterns before implementing.
1---2name: woo-payments3description: Build WooCommerce payment gateways — WC_Payment_Gateway, direct/redirect/hosted integrations, tokenization, subscriptions support, refunds, and PCI compliance. Use when creating custom payment method integrations.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/woo-payments7---89# WooCommerce Payment Gateway Development1011## Before writing code1213**Fetch live docs**:141. Web-search `site:developer.woocommerce.com payment gateway api` for payment gateway guide152. Web-search `woocommerce payment gateway tutorial` for implementation patterns163. Fetch `https://woocommerce.github.io/code-reference/classes/WC-Payment-Gateway.html` for class reference1718## Gateway Architecture1920### Base Class: WC_Payment_Gateway2122All gateways extend `WC_Payment_Gateway` (which extends `WC_Settings_API`):2324| Property | Description |25|----------|-------------|26| `$id` | Unique gateway identifier |27| `$method_title` | Admin-facing title |28| `$method_description` | Admin-facing description |29| `$title` | Customer-facing title |30| `$description` | Customer-facing description |31| `$icon` | URL to gateway icon |32| `$has_fields` | Whether gateway has payment fields on checkout |33| `$supports` | Array of supported features |3435### Registration3637Filter `woocommerce_payment_gateways`:38```php39add_filter( 'woocommerce_payment_gateways', function( $gateways ) {40 $gateways[] = 'My_Payment_Gateway';41 return $gateways;42});43```4445## Implementation Methods4647### Required Methods4849- **`__construct()`** — set `$id`, `$method_title`, `$supports`, call `init_form_fields()`, `init_settings()`, load saved settings, register `process_admin_options` hook50- **`init_form_fields()`** — define admin settings (API keys, sandbox mode, etc.)51- **`process_payment( $order_id )`** — core payment logic, returns `result` + `redirect` array5253### Optional Methods5455- `payment_fields()` — render custom payment form HTML on checkout56- `validate_fields()` — validate payment form input57- `process_refund( $order_id, $amount, $reason )` — handle refunds58- `get_icon()` — customize the gateway icon display5960### process_payment Return Format6162```php63return [64 'result' => 'success', // or 'failure'65 'redirect' => $order->get_checkout_order_received_url(),66];67```6869## Integration Models7071### Direct Integration7273Gateway processes payment inline:741. Collect card data via `payment_fields()` (or tokenized via JS SDK)752. Call payment processor API in `process_payment()`763. Mark order: `$order->payment_complete( $transaction_id )`774. Return success with redirect to thank-you page7879### Redirect Integration8081Customer redirected to external payment page:821. `process_payment()` returns redirect URL to processor832. Processor handles payment and redirects back843. Handle return via a webhook or callback URL854. Process the response and update order status8687### Hosted/Iframe Integration8889Payment form loaded in iframe on checkout page:90- Set `$has_fields = true`91- Render iframe/JS SDK in `payment_fields()`92- Handle tokenization callback9394## Supports Array9596```php97$this->supports = [98 'products', // Basic payment support99 'refunds', // process_refund()100 'tokenization', // Saved payment methods101 'subscriptions', // WooCommerce Subscriptions102 'subscription_cancellation',103 'subscription_reactivation',104 'subscription_suspension',105 'subscription_amount_changes',106 'subscription_date_changes',107];108```109110## Tokenization (Saved Payment Methods)111112### WC_Payment_Token System113114- Extend `WC_Payment_Token_CC` (credit cards) or `WC_Payment_Token` (generic)115- `$this->supports[] = 'tokenization'`116- Override `tokenization_script()` to enqueue JS117- Save tokens via `WC_Payment_Tokens::set_users_default()`118- Customer manages saved methods in My Account > Payment Methods119120## Webhook/IPN Handling121122### Registering Webhook Endpoints123124Use `WC_API` to register callback URLs:125- `add_action( 'woocommerce_api_{$id}', [ $this, 'handle_webhook' ] )`126- Callback URL: `home_url( '/wc-api/{$id}/' )`127- Verify signatures, process payment notifications, update order status128129## Order Status Management130131- `$order->update_status( 'processing', 'Payment received' )` — status + note132- `$order->payment_complete( $transaction_id )` — marks paid, triggers emails133- `$order->update_status( 'failed', 'Payment failed' )` — mark failed134- `$order->add_order_note( 'Note text' )` — add admin/customer note135136## Block Checkout Support137138For block-based checkout, gateways need a JS integration:1391. Register a payment method via `@woocommerce/blocks-registry` → `registerPaymentMethod()`1402. Provide React components for: `content`, `edit`, `label`1413. Define `canMakePayment` callback1424. Handle payment data submission via `onPaymentSetup` event143144## Best Practices145146- **Never** log or store raw credit card data147- Always use sandbox/test mode for development148- Verify webhook signatures to prevent spoofing149- Handle all error states gracefully with clear customer messages150- Support refunds if the processor allows them151- Declare `cart_checkout_blocks` compatibility and provide block checkout integration152- Use `$order->payment_complete()` — it handles status, stock reduction, and email triggers153- Store transaction IDs via `$order->set_transaction_id()`154155Fetch the WooCommerce payment gateway documentation and code reference for exact method signatures, supported features, and block checkout integration patterns before implementing.