Payment Gateway Development

SLSWC provides a framework for building WooCommerce payment gateways that support subscriptions, block checkout, and webhook handling.

Architecture

SLSWC_Gateway_Interface (interface)
    |
SLSWC_Abstract_Payment_Gateway (abstract, extends WC_Payment_Gateway_CC)
    |
+-- SLSWC_Payment_Gateway_Stripe
+-- SLSWC_Payment_Gateway_Polar
+-- SLSWC_Payment_Gateway_Payfast
+-- SLSWC_Payment_Gateway_Paypal

Gateway Interface

Source: includes/woocommerce/gateways/interface/slswc-gateway-interface.php

All gateways must implement SLSWC_Gateway_Interface:

interface SLSWC_Gateway_Interface {
    /**
     * Initialize the gateway hooks.
     */
    public function init_hooks();

    /**
     * Initialize the form fields for the gateway settings.
     */
    public function init_form_fields();
}

Abstract Base Class

Source: includes/woocommerce/gateways/abstract/class-slswc-abstract-payment-gateway.php

SLSWC_Abstract_Payment_Gateway extends WC_Payment_Gateway_CC and provides:

Property	Type	Description
$id	string	Gateway identifier
$title	string	Gateway display title
$description	string	Gateway description shown at checkout
$instructions	string	Post-checkout instructions
$supports	array	Supported features (e.g., products, refunds, subscriptions)

Helper Method

public function get_locale(): string

Returns the site locale normalized for Stripe's expectations (handles Norwegian dialect edge cases).

Registering a Custom Gateway

Use the slswc_payment_gateways filter to register your gateway class:

add_filter( 'slswc_payment_gateways', function ( $gateways ) {
    $gateways[] = 'My_Custom_Gateway';
    return $gateways;
} );

The filter is applied in SLSWC_Payment_Gateways::__construct(). Default gateways:

array(
    'SLSWC_Payment_Gateway_Stripe',
    'SLSWC_Payment_Gateway_Polar',
    'SLSWC_Payment_Gateway_Payfast',
    'SLSWC_Payment_Gateway_Paypal',
)

Gateway Class Structure

A minimal custom gateway:

class My_Custom_Gateway extends SLSWC_Abstract_Payment_Gateway
    implements SLSWC_Gateway_Interface {

    public function __construct() {
        $this->id                 = 'slswc_my_gateway';
        $this->method_title       = 'My Gateway';
        $this->method_description = 'Pay with My Gateway';
        $this->supports           = array( 'products', 'refunds' );
        $this->has_fields         = true;

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

        $this->title       = $this->get_option( 'title', 'My Gateway' );
        $this->description = $this->get_option( 'description', 'Pay securely.' );
    }

    public function init_hooks() {
        add_action(
            'woocommerce_update_options_payment_gateways_' . $this->id,
            array( $this, 'process_admin_options' )
        );
    }

    public function init_form_fields() {
        $this->form_fields = array(
            'enabled' => array(
                'title'   => 'Enable/Disable',
                'type'    => 'checkbox',
                'label'   => 'Enable My Gateway',
                'default' => 'no',
            ),
            'title' => array(
                'title'   => 'Title',
                'type'    => 'text',
                'default' => 'My Gateway',
            ),
        );
    }

    public function process_payment( $order_id ) {
        $order = wc_get_order( $order_id );
        // ... payment processing logic ...

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

Block Checkout Integration

SLSWC supports WooCommerce block-based checkout. Each gateway has a blocks integration class.

Pattern: includes/woocommerce/gateways/{gateway}/class-slswc-{gateway}-blocks-integration.php

To add block checkout support, create a class extending AbstractPaymentMethodType:

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

class My_Gateway_Blocks_Integration extends AbstractPaymentMethodType {
    protected $name = 'slswc_my_gateway';

    public function initialize() {
        $this->settings = get_option( 'woocommerce_slswc_my_gateway_settings', array() );
    }

    public function is_active() {
        return ! empty( $this->settings['enabled'] ) && 'yes' === $this->settings['enabled'];
    }

    public function get_payment_method_script_handles() {
        wp_register_script(
            'slswc-my-gateway-blocks',
            plugins_url( 'assets/js/my-gateway-blocks.js', MY_PLUGIN_FILE ),
            array( 'wc-blocks-registry', 'wc-settings', 'wp-element' ),
            '1.0.0',
            true
        );
        return array( 'slswc-my-gateway-blocks' );
    }

    public function get_payment_method_data() {
        return array(
            'title'       => $this->settings['title'] ?? 'My Gateway',
            'description' => $this->settings['description'] ?? '',
        );
    }
}

Register it in the woocommerce_blocks_payment_method_type_registration action:

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

Webhook Handling

SLSWC provides a centralized webhook routing system.

Webhook URL Format

https://your-site.com/slswc/webhook/{gateway_slug}

All webhook requests are verified using the gateway's signing secret before processing. Unsigned or invalid requests are rejected.

Getting the Webhook URL

$url = SLSWC_Payment_Gateways::get_webhook_url( 'my_gateway' );
// https://your-site.com/slswc/webhook/my_gateway

Handling Webhooks

If your gateway needs webhook support, you need to:

1. Add your gateway slug to the rewrite rule (or use init to register your own).
2. Implement a handle_webhook() method on your gateway class.
3. The method is called by SLSWC_Payment_Gateways::handle_webhook_routes().

Subscription Payments

When a subscription payment retry succeeds, gateways should fire:

do_action( 'slswc_retry_payment_succeeded', $subscription->id );

This action triggers SLSWC to update the subscription status and reset retry counters.

Supported Features

Payment gateways can declare supported features via the $supports property:

$this->supports = array(
    'products',
    'refunds',
    'tokenization',
    'add_payment_method',
);

Form Field Filters

Filter	Description
slswc_payment_gateway_form_fields	Filter Stripe gateway settings fields
slswc_payfast_gateway_form_fields	Filter PayFast gateway settings fields