Lesson 6.2. Payment Gateway

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_gateways filter
  • 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 AbstractPaymentMethodType class + registration on woocommerce_blocks_payment_method_type_registration + JS registerPaymentMethod

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
<?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
<?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
<?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

SymptomCauseFix
The gateway is in classic checkout but not in block checkoutNo blocks integrationAbstractPaymentMethodType + JS registerPaymentMethod
The order is paid twice / duplicate emailsThe webhook arrived twiceCheck is_paid() before payment_complete()
Anyone can "pay" an orderA webhook without a signature checkhash_hmac + hash_equals
The provider's amount differs by a centFloat arithmeticConvert 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 through wc_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.

wp / curl — Module 6. Orders, Payments, Shipping

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.

Save your progress

Sign in or create a free account to mark lessons as completed and continue the whole course. You will come back to this lesson.