Goal
Write a payment gateway that redirects to the provider, handles the webhook and supports block checkout.
Key concepts
- A class
extends WC_Payment_Gateway:id,method_title,init_form_fields(),process_payment() - Registration: the
woocommerce_payment_gatewaysfilter process_payment()returns[ 'result' => 'success', 'redirect' => $url ]- The provider's webhook — a REST route or
woocommerce_api_{id}; checking the signature is mandatory - Repeated webhooks are normal: processing must be idempotent
- Block checkout: an
AbstractPaymentMethodTypeclass + registration onwoocommerce_blocks_payment_method_type_registration+ JSregisterPaymentMethod
Diagram
sequenceDiagram
participant C as Customer
participant W as WooCommerce
participant G as Your gateway
participant P as Provider
C->>W: Place order (Store API / form)
W->>G: process_payment(order_id)
G->>P: create payment
P-->>G: payment_url
G-->>C: redirect to payment_url
C->>P: payment
P->>W: webhook (signature)
W->>G: verify the signature
G->>W: payment_complete(txn_id)
Code
The gateway (shortened):
<?php
class My_Gateway extends WC_Payment_Gateway {
public function __construct() {
$this->id = 'my_pay';
$this->method_title = 'MyPay';
$this->method_description = 'Card payment through MyPay';
$this->has_fields = false;
$this->supports = [ 'products', 'refunds' ];
$this->init_form_fields();
$this->init_settings();
$this->title = $this->get_option( 'title' );
add_action( "woocommerce_update_options_payment_gateways_{$this->id}", [ $this, 'process_admin_options' ] );
}
public function init_form_fields() {
$this->form_fields = [
'enabled' => [ 'title' => 'Enable', 'type' => 'checkbox', 'default' => 'no' ],
'title' => [ 'title' => 'Title', 'type' => 'text', 'default' => 'Card payment' ],
'secret_key' => [ 'title' => 'Secret key', 'type' => 'password' ],
];
}
public function process_payment( $order_id ) {
$order = wc_get_order( $order_id );
$payment = My_Pay_Client::create( [
'amount' => (int) round( $order->get_total() * 100 ),
'currency' => $order->get_currency(),
'reference' => $order->get_order_key(),
'return_url' => $this->get_return_url( $order ),
'webhook_url' => rest_url( 'my-pay/v1/webhook' ),
] );
$order->update_status( 'pending', 'Waiting for MyPay payment' );
return [ 'result' => 'success', 'redirect' => $payment['url'] ];
}
}
add_filter( 'woocommerce_payment_gateways', static function ( array $gateways ): array {
$gateways[] = My_Gateway::class;
return $gateways;
} );
A webhook with a signature check and idempotency:
<?php
add_action( 'rest_api_init', static function () {
register_rest_route( 'my-pay/v1', '/webhook', [
'methods' => 'POST',
'permission_callback' => '__return_true', // access is checked by the signature below
'callback' => static function ( WP_REST_Request $request ) {
$settings = get_option( 'woocommerce_my_pay_settings', [] );
$expected = hash_hmac( 'sha256', $request->get_body(), $settings['secret_key'] ?? '' );
if ( ! hash_equals( $expected, (string) $request->get_header( 'x-mypay-signature' ) ) ) {
return new WP_REST_Response( [ 'error' => 'bad signature' ], 401 );
}
$data = $request->get_json_params();
$order = wc_get_order( wc_get_order_id_by_order_key( $data['reference'] ?? '' ) );
if ( ! $order ) {
return new WP_REST_Response( [ 'error' => 'order not found' ], 404 );
}
if ( 'paid' === ( $data['status'] ?? '' ) && ! $order->is_paid() ) {
$order->payment_complete( sanitize_text_field( $data['transaction_id'] ?? '' ) );
}
return new WP_REST_Response( [ 'ok' => true ], 200 );
},
] );
} );
Block checkout support (the PHP part):
<?php
use Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType;
use Automattic\WooCommerce\Blocks\Payments\PaymentMethodRegistry;
final class My_Gateway_Blocks extends AbstractPaymentMethodType {
protected $name = 'my_pay';
public function initialize() {
$this->settings = get_option( 'woocommerce_my_pay_settings', [] );
}
public function is_active() {
return 'yes' === ( $this->settings['enabled'] ?? 'no' );
}
public function get_payment_method_script_handles() {
wp_register_script( 'my-pay-blocks', plugins_url( 'build/blocks.js', __FILE__ ), [ 'wc-blocks-registry', 'wp-element' ], '1.0.0', true );
return [ 'my-pay-blocks' ];
}
public function get_payment_method_data() {
return [ 'title' => $this->settings['title'] ?? 'MyPay' ];
}
}
add_action( 'woocommerce_blocks_payment_method_type_registration', static function ( PaymentMethodRegistry $registry ) {
$registry->register( new My_Gateway_Blocks() );
} );
Common mistakes
| Symptom | Cause | Fix |
|---|---|---|
| The gateway is in classic checkout but not in block checkout | No blocks integration | AbstractPaymentMethodType + JS registerPaymentMethod |
| The order is paid twice / duplicate emails | The webhook arrived twice | Check is_paid() before payment_complete() |
| Anyone can "pay" an order | A webhook without a signature check | hash_hmac + hash_equals |
| The provider's amount differs by a cent | Float arithmetic | Convert to minor units with round() |
Weak and strong answer
Question: How do you handle a webhook from a payment provider?
Weak answer. Receive the POST and set the order status to completed.
Strong answer. I check the signature (HMAC with the secret,
hash_equals) and find the order by the order key, not by an ID from the request. If the order is already paid, I just answer 200, because providers repeat webhooks. Otherwise —payment_complete( $txn_id ), not a manual status, so that stock, emails and hooks fire. I log throughwc_get_logger().
Why the second is stronger: Security, idempotency and the right WooCommerce API in one answer.
Practice
Write a stub gateway "Test payment": process_payment() redirects to a page that imitates the provider and sends a signed webhook. In the terminal check a webhook with a wrong signature, with the right one, and the same webhook again: the order must not be paid twice.
Interview Questions
An array with result (success or failure) and redirect — the URL to send the customer to: the provider's page or the thank-you page.
Providers retry delivery if they didn't get a 200 in time, and they may send several events about one payment. Processing it again must not change the result.
Add refunds to $this->supports and implement process_refund( $order_id, $amount, $reason ) calling the provider's API.