Payment Gateways

wp wc payment_gateway list --user=admin --fields=id,title,enabled,method_title --format=table

id      title                  enabled  method_title
bacs    Direct bank transfer   1        Direct bank transfer
cheque  Check payments                  Check payments
cod     Cash on delivery       1        Cash on delivery

add_action( 'plugins_loaded', 'init_your_gateway_class' );

function init_your_gateway_class() {
	class WC_Gateway_Your_Gateway extends WC_Payment_Gateway {}
}

function add_your_gateway_class( $methods ) {
	$methods[] = 'WC_Gateway_Your_Gateway';
	return $methods;
}
add_filter( 'woocommerce_payment_gateways', 'add_your_gateway_class' );

pocket-coffee-payments/
  pocket-coffee-payments.php                      plugin header, compatibility, registration
  includes/class-pocketcoffee-pay-stub.php        the fake provider (tokens in, charge or refund out)
  includes/class-wc-gateway-pocketcoffee-pay.php  the card gateway
  includes/class-wc-gateway-pocketcoffee-ctx.php  a second gateway paid through the Store API hook
  includes/class-pocketcoffee-pay-blocks.php      Checkout block integration (PHP)
  assets/checkout.js                              Checkout block integration (JavaScript, no build step)

<?php
/**
 * A stand-in for a payment provider's API. It never sees a card number: it only accepts tokens.
 *
 * @package PocketCoffee\Payments
 */

defined( 'ABSPATH' ) || exit;

/**
 * Deterministic fake provider used by the examples.
 */
class PocketCoffee_Pay_Stub {

	/**
	 * Tokens the fake provider understands (what hosted fields would return in a real integration).
	 *
	 * @return array<string,array>
	 */
	public static function tokens() {
		return array(
			'tok_visa'       => array(
				'status'    => 'approved',
				'brand'     => 'visa',
				'last4'     => '4242',
				'exp_month' => '12',
				'exp_year'  => '2030',
			),
			'tok_mastercard' => array(
				'status'    => 'approved',
				'brand'     => 'mastercard',
				'last4'     => '5454',
				'exp_month' => '11',
				'exp_year'  => '2031',
			),
			'tok_decline'    => array(
				'status'    => 'declined',
				'brand'     => 'visa',
				'last4'     => '0002',
				'exp_month' => '01',
				'exp_year'  => '2030',
			),
			'tok_pending'    => array(
				'status'    => 'pending',
				'brand'     => 'visa',
				'last4'     => '3155',
				'exp_month' => '06',
				'exp_year'  => '2030',
			),
			'tok_norefund'   => array(
				'status'    => 'approved',
				'brand'     => 'visa',
				'last4'     => '9995',
				'exp_month' => '03',
				'exp_year'  => '2030',
			),
		);
	}

	/**
	 * Create a charge.
	 *
	 * @param string $token        Provider token.
	 * @param int    $amount_minor Amount in minor units (cents).
	 * @param string $currency     ISO 4217 currency.
	 * @param string $idempotency  Idempotency key: the same key must always yield the same charge.
	 * @return array|WP_Error
	 */
	public static function charge( $token, $amount_minor, $currency, $idempotency ) {
		$tokens = self::tokens();
		if ( ! isset( $tokens[ $token ] ) ) {
			return new WP_Error( 'invalid_token', 'Unknown payment token.' );
		}
		$data   = $tokens[ $token ];
		$prefix = 'tok_norefund' === $token ? 'pcp_nr_' : 'pcp_';
		return array(
			'id'       => $prefix . substr( hash( 'sha256', $idempotency ), 0, 12 ),
			'status'   => $data['status'],
			'amount'   => $amount_minor,
			'currency' => $currency,
			'card'     => array(
				'brand'     => $data['brand'],
				'last4'     => $data['last4'],
				'exp_month' => $data['exp_month'],
				'exp_year'  => $data['exp_year'],
			),
			'message'  => 'declined' === $data['status'] ? 'Your card was declined.' : '',
		);
	}

	/**
	 * Refund (part of) a charge.
	 *
	 * @param string $charge_id    Charge ID returned by charge().
	 * @param int    $amount_minor Amount in minor units.
	 * @return array|WP_Error
	 */
	public static function refund( $charge_id, $amount_minor ) {
		if ( 0 === strpos( $charge_id, 'pcp_nr_' ) ) {
			return new WP_Error( 'refund_refused', 'The provider refused the refund.' );
		}
		return array(
			'id'     => 're_' . substr( hash( 'sha256', $charge_id . $amount_minor . microtime() ), 0, 12 ),
			'status' => 'succeeded',
			'amount' => $amount_minor,
		);
	}
}

<?php
/**
 * Plugin Name:       Pocket Coffee Payments
 * Description:       Pocket Coffee Pay: a card payment gateway for classic and block checkout, with saved cards and refunds.
 * Version:           1.0.0
 * Requires at least: 7.0
 * Requires PHP:      7.4
 * Requires Plugins:  woocommerce
 * Text Domain:       pocket-coffee-payments
 * License:           GPL-2.0-or-later
 *
 * @package PocketCoffee\Payments
 */

defined( 'ABSPATH' ) || exit;

define( 'POCKET_COFFEE_PAYMENTS_FILE', __FILE__ );

// 1. Declare compatibility before WooCommerce initializes.
add_action(
	'before_woocommerce_init',
	static function () {
		if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
			\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', POCKET_COFFEE_PAYMENTS_FILE, true );
			\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'cart_checkout_blocks', POCKET_COFFEE_PAYMENTS_FILE, true );
		}
	}
);

// 2. Load the gateway classes once WooCommerce is available and register them.
add_action(
	'plugins_loaded',
	static function () {
		if ( ! class_exists( 'WC_Payment_Gateway' ) ) {
			return;
		}
		require_once __DIR__ . '/includes/class-pocketcoffee-pay-stub.php';
		require_once __DIR__ . '/includes/class-wc-gateway-pocketcoffee-pay.php';
		require_once __DIR__ . '/includes/class-wc-gateway-pocketcoffee-ctx.php';

		add_filter(
			'woocommerce_payment_gateways',
			static function ( $gateways ) {
				$gateways[] = 'WC_Gateway_PocketCoffee_Pay';
				$gateways[] = 'WC_Gateway_PocketCoffee_Ctx';
				return $gateways;
			}
		);
	}
);

// 3. Register the block-based checkout integration.
add_action(
	'woocommerce_blocks_loaded',
	static function () {
		if ( ! class_exists( \Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType::class ) ) {
			return;
		}
		require_once __DIR__ . '/includes/class-pocketcoffee-pay-blocks.php';

		add_action(
			'woocommerce_blocks_payment_method_type_registration',
			static function ( \Automattic\WooCommerce\Blocks\Payments\PaymentMethodRegistry $registry ) {
				$registry->register( new PocketCoffee_Pay_Blocks() );
			}
		);
	}
);

wp wc hpos compatibility-info

7 compatible plugins found:

  EC Hello
  Pocket Coffee Architecture
  Pocket Coffee Checkout Fields
  Pocket Coffee Payments
  Pocket Coffee REST API
  Pocket Coffee Scheduler
  Pocket Coffee Taxes

0 incompatible plugins found

<?php
/**
 * Pocket Coffee Pay gateway.
 *
 * @package PocketCoffee\Payments
 */

use Automattic\WooCommerce\Enums\OrderStatus;
use Automattic\WooCommerce\Enums\PaymentGatewayFeature;

defined( 'ABSPATH' ) || exit;

/**
 * Direct card gateway: the shopper's card is tokenized in the browser, the server only handles the token.
 */
class WC_Gateway_PocketCoffee_Pay extends WC_Payment_Gateway {

	/**
	 * Constructor.
	 */
	public function __construct() {
		$this->id                 = 'pocketcoffee_pay';
		$this->icon               = '';
		$this->has_fields         = true;
		$this->method_title       = __( 'Pocket Coffee Pay', 'pocket-coffee-payments' );
		$this->method_description = __( 'Accept card payments with Pocket Coffee Pay (demo provider).', 'pocket-coffee-payments' );
		$this->supports           = array(
			PaymentGatewayFeature::PRODUCTS,
			PaymentGatewayFeature::REFUNDS,
			PaymentGatewayFeature::TOKENIZATION,
			PaymentGatewayFeature::ADD_PAYMENT_METHOD,
		);

		$this->init_form_fields();
		$this->init_settings();

		$this->title       = $this->get_option( 'title' );
		$this->description = $this->get_option( 'description' );
		$this->max_amount  = (float) $this->get_option( 'max_amount', 0 );

		add_action( 'woocommerce_update_options_payment_gateways_' . $this->id, array( $this, 'process_admin_options' ) );
		// WooCommerce loads every gateway before it fires the wc-api action, so the webhook can be hooked here.
		// The action name is the lower-cased value of the wc-api query variable.
		add_action( 'woocommerce_api_' . $this->id, array( $this, 'handle_webhook' ) );
	}

	/**
	 * Settings shown under WooCommerce > Settings > Payments.
	 */
	public function init_form_fields() {
		$this->form_fields = array(
			'enabled'     => array(
				'title'   => __( 'Enable/Disable', 'pocket-coffee-payments' ),
				'type'    => 'checkbox',
				'label'   => __( 'Enable Pocket Coffee Pay', 'pocket-coffee-payments' ),
				'default' => 'no',
			),
			'title'       => array(
				'title'       => __( 'Title', 'pocket-coffee-payments' ),
				'type'        => 'text',
				'description' => __( 'Shown to the shopper at checkout.', 'pocket-coffee-payments' ),
				'default'     => __( 'Card (Pocket Coffee Pay)', 'pocket-coffee-payments' ),
				'desc_tip'    => true,
			),
			'description' => array(
				'title'   => __( 'Description', 'pocket-coffee-payments' ),
				'type'    => 'textarea',
				'default' => __( 'Pay securely with your card.', 'pocket-coffee-payments' ),
			),
			'secret_key'  => array(
				'title'       => __( 'Webhook secret', 'pocket-coffee-payments' ),
				'type'        => 'password',
				'description' => __( 'Used to verify the signature of webhook calls.', 'pocket-coffee-payments' ),
				'default'     => '',
				'desc_tip'    => true,
			),
			'max_amount'  => array(
				'title'       => __( 'Maximum order total', 'pocket-coffee-payments' ),
				'type'        => 'price',
				'description' => __( 'The gateway is hidden above this total. 0 means no limit.', 'pocket-coffee-payments' ),
				'default'     => '0',
				'desc_tip'    => true,
			),
		);
	}

	/**
	 * Classic checkout: markup shown inside the payment box. A real gateway mounts the provider's hosted fields here.
	 */
	public function payment_fields() {
		$description = $this->get_description();
		if ( $description ) {
			echo wp_kses_post( wpautop( wptexturize( $description ) ) );
		}
		if ( $this->supports( PaymentGatewayFeature::TOKENIZATION ) && is_user_logged_in() ) {
			$this->saved_payment_methods();
		}
		echo '<p class="form-row"><label for="pocketcoffee_pay_token">' . esc_html__( 'Test token', 'pocket-coffee-payments' ) . '</label>';
		echo '<select id="pocketcoffee_pay_token" name="pocketcoffee_pay_token">';
		foreach ( array_keys( PocketCoffee_Pay_Stub::tokens() ) as $token ) {
			echo '<option value="' . esc_attr( $token ) . '">' . esc_html( $token ) . '</option>';
		}
		echo '</select></p>';
		if ( $this->supports( PaymentGatewayFeature::TOKENIZATION ) && is_user_logged_in() ) {
			$this->save_payment_method_checkbox();
		}
	}

	/**
	 * Validate the posted fields before an order is created.
	 *
	 * @return bool
	 */
	public function validate_fields() {
		if ( $this->get_posted_token_id() ) {
			return true;
		}
		$token = $this->get_posted_provider_token();
		if ( '' === $token || ! isset( PocketCoffee_Pay_Stub::tokens()[ $token ] ) ) {
			wc_add_notice( __( 'Please enter your card details.', 'pocket-coffee-payments' ), 'error' );
			return false;
		}
		return true;
	}

	/**
	 * Take the payment for an order.
	 *
	 * @param int $order_id Order ID.
	 * @return array
	 */
	public function process_payment( $order_id ) {
		$order = wc_get_order( $order_id );
		if ( ! $order ) {
			return array( 'result' => 'failure' );
		}

		// A saved card (token ID chosen by the shopper) or a fresh provider token from the browser.
		$saved = $this->get_posted_token_id();
		if ( $saved ) {
			$token_obj = WC_Payment_Tokens::get( $saved );
			if ( ! $token_obj || $token_obj->get_user_id() !== get_current_user_id() || $token_obj->get_gateway_id() !== $this->id ) {
				wc_add_notice( __( 'Invalid saved card.', 'pocket-coffee-payments' ), 'error' );
				return array( 'result' => 'failure' );
			}
			$provider_token = $token_obj->get_token();
		} else {
			$provider_token = $this->get_posted_provider_token();
		}

		$minor    = (int) round( (float) $order->get_total() * 100 );
		$response = PocketCoffee_Pay_Stub::charge( $provider_token, $minor, $order->get_currency(), 'order-' . $order->get_order_key() );

		if ( is_wp_error( $response ) || 'declined' === $response['status'] ) {
			$message = is_wp_error( $response ) ? $response->get_error_message() : $response['message'];
			$order->add_order_note( sprintf( 'Pocket Coffee Pay: payment declined (%s).', $message ) );
			wc_add_notice( $message, 'error' );
			return array( 'result' => 'failure' );
		}

		$order->update_meta_data( '_pcp_charge_id', $response['id'] );
		$order->set_payment_method( $this );

		if ( 'pending' === $response['status'] ) {
			// Asynchronous method: wait for the webhook.
			$order->set_transaction_id( $response['id'] );
			$order->update_status( OrderStatus::ON_HOLD, __( 'Awaiting Pocket Coffee Pay confirmation.', 'pocket-coffee-payments' ) );
		} else {
			$order->payment_complete( $response['id'] );
			$order->add_order_note( sprintf( 'Pocket Coffee Pay: charge %s approved.', $response['id'] ) );
		}

		if ( ! $saved && is_user_logged_in() && $this->wants_to_save_card() ) {
			$this->save_card( get_current_user_id(), $provider_token, $response['card'] );
		}

		wc()->cart->empty_cart();

		return array(
			'result'   => 'success',
			'redirect' => $this->get_return_url( $order ),
		);
	}

	/**
	 * Refund through the provider. Called by wc_refund_payment() when the merchant chooses "Refund via ...".
	 *
	 * @param int        $order_id Order ID.
	 * @param float|null $amount   Amount to refund.
	 * @param string     $reason   Reason entered by the merchant.
	 * @return bool|WP_Error
	 */
	public function process_refund( $order_id, $amount = null, $reason = '' ) {
		$order = wc_get_order( $order_id );
		if ( ! $order || ! $order->get_transaction_id() ) {
			return new WP_Error( 'no_transaction', __( 'This order has no transaction ID.', 'pocket-coffee-payments' ) );
		}
		if ( null === $amount || (float) $amount <= 0 ) {
			return new WP_Error( 'invalid_amount', __( 'Invalid refund amount.', 'pocket-coffee-payments' ) );
		}

		$response = PocketCoffee_Pay_Stub::refund( $order->get_transaction_id(), (int) round( (float) $amount * 100 ) );
		if ( is_wp_error( $response ) ) {
			$order->add_order_note( sprintf( 'Pocket Coffee Pay: refund failed (%s).', $response->get_error_message() ) );
			return $response;
		}

		$order->add_order_note(
			sprintf( 'Pocket Coffee Pay: refunded %1$s %2$s (refund %3$s). %4$s', $order->get_currency(), wc_format_decimal( $amount, 2 ), $response['id'], $reason )
		);
		return true;
	}

	/**
	 * My account > Payment methods > Add payment method.
	 *
	 * @return array
	 */
	public function add_payment_method() {
		$provider_token = $this->get_posted_provider_token();
		$cards          = PocketCoffee_Pay_Stub::tokens();
		if ( ! isset( $cards[ $provider_token ] ) || 'declined' === $cards[ $provider_token ]['status'] ) {
			wc_add_notice( __( 'The card could not be saved.', 'pocket-coffee-payments' ), 'error' );
			return array(
				'result'   => 'failure',
				'redirect' => wc_get_endpoint_url( 'payment-methods' ),
			);
		}
		$this->save_card( get_current_user_id(), $provider_token, $cards[ $provider_token ] );
		return array(
			'result'   => 'success',
			'redirect' => wc_get_endpoint_url( 'payment-methods' ),
		);
	}

	/**
	 * Webhook: https://example.com/?wc-api=pocketcoffee_pay with a JSON body and an HMAC-SHA256 signature header.
	 */
	public function handle_webhook() {
		$payload   = file_get_contents( 'php://input' );
		$signature = isset( $_SERVER['HTTP_X_PCP_SIGNATURE'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_X_PCP_SIGNATURE'] ) ) : '';
		$secret    = (string) $this->get_option( 'secret_key' );

		if ( '' === $secret || ! hash_equals( hash_hmac( 'sha256', $payload, $secret ), $signature ) ) {
			status_header( 403 );
			exit;
		}

		$event = json_decode( $payload, true );
		$order = ( is_array( $event ) && ! empty( $event['order_id'] ) ) ? wc_get_order( absint( $event['order_id'] ) ) : false;
		if ( ! $order || $order->get_payment_method() !== $this->id ) {
			status_header( 404 );
			exit;
		}

		// Idempotent: a repeated delivery must not pay the order twice.
		if ( 'charge.succeeded' === $event['type'] && ! $order->is_paid() ) {
			$order->payment_complete( (string) $event['charge_id'] );
			$order->add_order_note( 'Pocket Coffee Pay: webhook confirmed the charge.' );
		} elseif ( 'charge.failed' === $event['type'] && $order->has_status( OrderStatus::ON_HOLD ) ) {
			$order->update_status( OrderStatus::FAILED, 'Pocket Coffee Pay: webhook reported a failed charge.' );
		}

		status_header( 200 );
		exit;
	}

	/**
	 * Provider token posted by the browser (classic form field or block payment data).
	 *
	 * @return string
	 */
	private function get_posted_provider_token() {
		// phpcs:ignore WordPress.Security.NonceVerification.Missing -- WooCommerce verifies the checkout nonce before calling the gateway.
		return isset( $_POST['pocketcoffee_pay_token'] ) ? sanitize_text_field( wp_unslash( $_POST['pocketcoffee_pay_token'] ) ) : '';
	}

	/**
	 * ID of a saved token chosen by the shopper, or 0.
	 *
	 * @return int
	 */
	private function get_posted_token_id() {
		$key = 'wc-' . $this->id . '-payment-token';
		// phpcs:ignore WordPress.Security.NonceVerification.Missing -- see above.
		if ( isset( $_POST[ $key ] ) && 'new' !== $_POST[ $key ] ) {
			// phpcs:ignore WordPress.Security.NonceVerification.Missing -- see above.
			return absint( wp_unslash( $_POST[ $key ] ) );
		}
		return 0;
	}

	/**
	 * Whether the shopper ticked "Save to account".
	 *
	 * @return bool
	 */
	private function wants_to_save_card() {
		$key = 'wc-' . $this->id . '-new-payment-method';
		// phpcs:ignore WordPress.Security.NonceVerification.Missing -- see above.
		return isset( $_POST[ $key ] ) && wc_string_to_bool( sanitize_text_field( wp_unslash( $_POST[ $key ] ) ) );
	}

	/**
	 * Store a card as a WooCommerce payment token. The "token" is the provider's reusable token, never a card number.
	 *
	 * @param int    $user_id        Customer.
	 * @param string $provider_token Provider token.
	 * @param array  $card           Card metadata (brand, last4, exp_month, exp_year).
	 */
	private function save_card( $user_id, $provider_token, array $card ) {
		$token = new WC_Payment_Token_CC();
		$token->set_token( $provider_token );
		$token->set_gateway_id( $this->id );
		$token->set_user_id( $user_id );
		$token->set_card_type( $card['brand'] );
		$token->set_last4( $card['last4'] );
		$token->set_expiry_month( $card['exp_month'] );
		$token->set_expiry_year( $card['exp_year'] );

		// The money is already taken at this point: a token that cannot be saved must not turn the checkout into an error.
		try {
			$token->save();
		} catch ( Exception $e ) {
			wc_get_logger()->error( 'Could not save the card token: ' . $e->getMessage(), array( 'source' => 'pocketcoffee-pay' ) );
		}
	}
}

wp wc payment_gateway update pocketcoffee_pay --enabled=true --settings='{"secret_key":"whsec_xxxxxxxx"}' --user=admin --porcelain
wp wc payment_gateway list --user=admin --fields=id,title,enabled --format=table

pocketcoffee_pay
id                title                     enabled
bacs              Direct bank transfer      1
cheque            Check payments
cod               Cash on delivery          1
pocketcoffee_pay  Card (Pocket Coffee Pay)  1
pocketcoffee_ctx  Pay by invoice            1

{
  "payment_method": "pocketcoffee_pay",
  "payment_data": [ { "key": "pocketcoffee_pay_token", "value": "tok_visa" } ],
  "billing_address": { "...": "..." },
  "shipping_address": { "...": "..." }
}

approved       -> 200 order 296 processing, payment_status success, redirect to /checkout/order-received/296/
declined       -> 400 woocommerce_rest_checkout_process_payment_error "Your card was declined."
pending        -> 200 order 298 on-hold, payment_status success, redirect to the order-received page
missing token  -> 400 woocommerce_rest_checkout_process_payment_error "Please enter your card details."
no refund      -> 200 order 300 processing
invoice, no PO -> 400 woocommerce_rest_checkout_process_payment_error "A purchase order number is required."
invoice + PO   -> 200 order 302 on-hold

Payment via Card (Pocket Coffee Pay) (pcp_d42701ecfdd1).
Pocket Coffee Pay: charge pcp_d42701ecfdd1 approved.

add_payment_method: {"result":"success","redirect":"\/payment-methods\/"}
token 1 type=CC default=true display=Visa ending in 4242 (expires 12/30) provider=tok_visa
token 2 type=CC default=false display=Mastercard ending in 5454 (expires 11/31) provider=tok_mastercard
saved-card payment: success status=processing txn=pcp_ef54f0de05f3
foreign token: failure notices=[{"notice":"Invalid saved card.","data":[]}]
save during checkout: success tokens now 3

token_id  gateway_id        token           type  is_default
1         pocketcoffee_pay  tok_visa        CC    1
2         pocketcoffee_pay  tok_mastercard  CC    0
3         pocketcoffee_pay  tok_norefund    CC    0

payment_token_id  meta_key      meta_value
1                 last4         4242
1                 expiry_year   2030
1                 expiry_month  12
1                 card_type     visa
...

curl -s -u ck_xxxxxxxx:cs_xxxxxxxx -H 'Content-Type: application/json' \
  -X POST https://shop.example.test/wp-json/wc/v3/orders/296/refunds \
  -d '{"amount":"5.00","reason":"Damaged bag","api_refund":true}'

refund 5.00 on order 296            -> refund id 304, refunded_payment true
refund on order 300 (tok_norefund)  -> woocommerce_rest_cannot_create_order_refund: The provider refused the refund.
refund on order 302 (no refunds)    -> woocommerce_rest_cannot_create_order_refund: The payment gateway for this order does not support automatic refunds.
api_refund false, 1.00 on order 296 -> refund id 307, refunded_payment false

<?php
/**
 * Block checkout integration for Pocket Coffee Pay.
 *
 * @package PocketCoffee\Payments
 */

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

defined( 'ABSPATH' ) || exit;

/**
 * Server-side description of the payment method for the Cart and Checkout blocks.
 */
final class PocketCoffee_Pay_Blocks extends AbstractPaymentMethodType {

	/**
	 * Must equal the gateway ID and the name used in registerPaymentMethod().
	 *
	 * @var string
	 */
	protected $name = 'pocketcoffee_pay';

	/**
	 * Load settings. Runs on every request: keep it cheap.
	 */
	public function initialize() {
		$this->settings = get_option( 'woocommerce_pocketcoffee_pay_settings', array() );
	}

	/**
	 * The script is only enqueued when the gateway is enabled.
	 *
	 * @return bool
	 */
	public function is_active() {
		return filter_var( $this->get_setting( 'enabled', false ), FILTER_VALIDATE_BOOLEAN ) || 'yes' === $this->get_setting( 'enabled' );
	}

	/**
	 * Register the client script and return its handle.
	 *
	 * @return string[]
	 */
	public function get_payment_method_script_handles() {
		wp_register_script(
			'pocket-coffee-pay-blocks',
			plugins_url( 'assets/checkout.js', POCKET_COFFEE_PAYMENTS_FILE ),
			array( 'wc-blocks-registry', 'wc-settings', 'wp-element', 'wp-html-entities', 'wp-i18n' ),
			'1.0.0',
			true
		);
		return array( 'pocket-coffee-pay-blocks' );
	}

	/**
	 * Data exposed to the script as wc.wcSettings.getSetting( 'pocketcoffee_pay_data' ).
	 *
	 * @return array
	 */
	public function get_payment_method_data() {
		return array(
			'title'       => $this->get_setting( 'title' ),
			'description' => $this->get_setting( 'description' ),
			'supports'    => $this->get_supported_features(),
			'tokens'      => array_keys( PocketCoffee_Pay_Stub::tokens() ),
		);
	}

	/**
	 * Features the Checkout block cross-checks against the cart content.
	 *
	 * @return string[]
	 */
	public function get_supported_features() {
		$gateway = WC()->payment_gateways()->payment_gateways()[ $this->name ] ?? null;
		return $gateway ? array_values( array_filter( $gateway->supports, static fn( $feature ) => in_array( $feature, array( 'products', 'refunds' ), true ) ) ) : array( 'products' );
	}
}

<script id="pocket-coffee-pay-blocks-js" src="http://localhost:8081/wp-content/plugins/pocket-coffee-payments/assets/checkout.js?ver=1.0.0">
...
"paymentMethodSortOrder":["bacs","cod","pocketcoffee_pay","pocketcoffee_ctx"],
"paymentMethodData":{"bacs":{...},"cod":{...},
 "pocketcoffee_pay":{"title":"Card (Pocket Coffee Pay)","description":"Pay securely with your card.",
 "supports":["products","refunds"],"tokens":["tok_visa","tok_mastercard","tok_decline","tok_pending","tok_norefund"]}}

( function () {
	const { registerPaymentMethod } = window.wc.wcBlocksRegistry;
	const { getPaymentMethodData } = window.wc.wcSettings;
	const { createElement, useState, useEffect } = window.wp.element;
	const { decodeEntities } = window.wp.htmlEntities;

	const settings = getPaymentMethodData( 'pocketcoffee_pay', {} );
	const title = decodeEntities( settings.title || 'Pocket Coffee Pay' );

	const Label = ( props ) => {
		const { PaymentMethodLabel } = props.components;
		return createElement( PaymentMethodLabel, { text: title } );
	};

	// Shown when the shopper picks "Card (Pocket Coffee Pay)". A real gateway mounts the provider's hosted fields here
	// and asks the provider for a token inside the onPaymentSetup observer.
	const Content = ( props ) => {
		const { eventRegistration, emitResponse, shouldSavePayment } = props;
		const { onPaymentSetup } = eventRegistration;
		const [ token, setToken ] = useState( 'tok_visa' );

		useEffect( () => {
			const unsubscribe = onPaymentSetup( () => {
				const paymentMethodData = { pocketcoffee_pay_token: token };
				if ( shouldSavePayment ) {
					paymentMethodData[ 'wc-pocketcoffee_pay-new-payment-method' ] = 'true';
				}
				return { type: emitResponse.responseTypes.SUCCESS, meta: { paymentMethodData } };
			} );
			return unsubscribe;
		}, [ onPaymentSetup, emitResponse.responseTypes.SUCCESS, token, shouldSavePayment ] );

		return createElement(
			'div',
			null,
			createElement( 'p', null, decodeEntities( settings.description || '' ) ),
			createElement(
				'select',
				{ value: token, onChange: ( e ) => setToken( e.target.value ) },
				( settings.tokens || [] ).map( ( t ) => createElement( 'option', { key: t, value: t }, t ) )
			)
		);
	};

	registerPaymentMethod( {
		name: 'pocketcoffee_pay',
		label: createElement( Label ),
		content: createElement( Content ),
		edit: createElement( Content ),
		canMakePayment: () => true,
		ariaLabel: title,
		placeOrderButtonLabel: 'Pay with card',
		supports: {
			features: settings.supports || [ 'products' ],
			showSavedCards: true,
			showSaveOption: true,
		},
	} );
}() );

name: pocketcoffee_pay | supports: {"features":["products","refunds"],"showSavedCards":true,"showSaveOption":true} | button label: Pay with card
onPaymentSetup result: {"type":"success","meta":{"paymentMethodData":{"pocketcoffee_pay_token":"tok_visa","wc-pocketcoffee_pay-new-payment-method":"true"}}}

<?php
/**
 * A second, minimal gateway that is processed through the Store API payment hook instead of process_payment().
 *
 * @package PocketCoffee\Payments
 */

use Automattic\WooCommerce\Enums\OrderStatus;
use Automattic\WooCommerce\StoreApi\Payments\PaymentContext;
use Automattic\WooCommerce\StoreApi\Payments\PaymentResult;

defined( 'ABSPATH' ) || exit;

/**
 * Pocket Coffee invoice: the order is accepted on hold, to be paid by bank transfer after the invoice is issued.
 */
class WC_Gateway_PocketCoffee_Ctx extends WC_Payment_Gateway {

	/**
	 * Constructor.
	 */
	public function __construct() {
		$this->id                 = 'pocketcoffee_ctx';
		$this->method_title       = __( 'Pocket Coffee invoice', 'pocket-coffee-payments' );
		$this->method_description = __( 'Pay by invoice (demo of the Store API payment hook).', 'pocket-coffee-payments' );
		$this->has_fields         = false;
		$this->supports           = array( 'products' );

		$this->init_form_fields();
		$this->init_settings();
		$this->title = $this->get_option( 'title' );

		add_action( 'woocommerce_update_options_payment_gateways_' . $this->id, array( $this, 'process_admin_options' ) );
		add_action( 'woocommerce_rest_checkout_process_payment_with_context', array( $this, 'process_with_context' ), 10, 2 );
	}

	/**
	 * Settings.
	 */
	public function init_form_fields() {
		$this->form_fields = array(
			'enabled' => array(
				'title'   => __( 'Enable/Disable', 'pocket-coffee-payments' ),
				'type'    => 'checkbox',
				'label'   => __( 'Enable invoice payments', 'pocket-coffee-payments' ),
				'default' => 'no',
			),
			'title'   => array(
				'title'   => __( 'Title', 'pocket-coffee-payments' ),
				'type'    => 'text',
				'default' => __( 'Pay by invoice', 'pocket-coffee-payments' ),
			),
		);
	}

	/**
	 * Called by the Store API for the Checkout block. When it sets a status, the legacy process_payment() path is skipped.
	 *
	 * @param PaymentContext $context Chosen payment method, order and client payment_data.
	 * @param PaymentResult  $result  Result object to fill.
	 * @throws Exception When the purchase order number is missing; the Store API turns it into a 400 error.
	 */
	public function process_with_context( PaymentContext $context, PaymentResult &$result ) {
		if ( $this->id !== $context->payment_method ) {
			return;
		}
		$purchase_order = isset( $context->payment_data['po_number'] ) ? $context->payment_data['po_number'] : '';
		if ( '' === $purchase_order ) {
			throw new Exception( esc_html__( 'A purchase order number is required.', 'pocket-coffee-payments' ) );
		}
		$context->order->update_meta_data( '_pcp_po_number', $purchase_order );
		$context->order->update_status( OrderStatus::ON_HOLD, __( 'Awaiting bank transfer for the invoice.', 'pocket-coffee-payments' ) );
		$result->set_status( 'success' );
		$result->set_redirect_url( $this->get_return_url( $context->order ) );
	}

	/**
	 * Classic checkout / pay page fallback.
	 *
	 * @param int $order_id Order ID.
	 * @return array
	 */
	public function process_payment( $order_id ) {
		$order = wc_get_order( $order_id );
		$order->update_status( OrderStatus::ON_HOLD, __( 'Awaiting bank transfer for the invoice.', 'pocket-coffee-payments' ) );
		wc()->cart->empty_cart();
		return array(
			'result'   => 'success',
			'redirect' => $this->get_return_url( $order ),
		);
	}
}