Tutor LMS Payment Gateway Architecture (Ollyo PaymentHub)

Tutor LMS payment gateway development means plugging three classes into Tutor's native e-commerce: a gateway class that extends Tutor\PaymentGateways\GatewayBase, a config class that extends Ollyo\PaymentHub\Core\Payment\BaseConfig, and a payment class that extends Ollyo\PaymentHub\Core\Payment\BasePayment. You register the first two through the tutor_payment_gateways_with_class and tutor_gateways_with_class filters, and Tutor handles the cart, orders, enrolment and the webhook route.

This article walks through that architecture as Themeum's own Tutor Stripe add-on uses it, so you can judge what a custom or regional gateway involves before you build one. It applies only when Tutor's native e-commerce is the monetisation engine; WooCommerce and EDD checkouts use their own gateway systems.

Checked against the source of Tutor LMS 4.1.3, Tutor LMS Pro 4.1.3 and Tutor Stripe 1.0.9 (October 2026). The gateway framework classes carry @since 3.0.0 tags, the release that introduced native e-commerce.

The three layers: Tutor, PaymentHub and the provider

The design separates WordPress concerns from payment-provider concerns:

The Ollyo\PaymentHub framework ships inside Tutor core, under ecommerce/PaymentGateways/Paypal/src, because the bundled PayPal gateway uses it. Its PaymentHub class takes a payment class name and a config class name, builds the config with createConfig(), injects it into the payment object, calls check() and throws InvalidConfigurationException if the check fails, then calls setup(). For the wider plugin structure, see our Tutor LMS architecture overview.

How Tutor finds a gateway

Core keeps a map from a gateway key to its classes. Ecommerce::payment_gateways_with_ref() starts with PayPal and runs the map through tutor_payment_gateways_with_class. Checkout and the webhook handler then pass the result through a second filter, tutor_gateways_with_class, which receives the requested key as its second argument. Tutor Stripe hooks both, each returning an entry of this shape:

'stripe' => array(
    'gateway_class' => StripeGateway::class,
    'config_class'  => StripeConfig::class,
),

A gateway is offered at checkout only when it is active in the payment settings and Ecommerce::is_payment_gateway_configured() returns true. That method instantiates your gateway, asks it for its config class and calls is_configured() inside a try block, so a missing method or a constructor that throws simply hides the gateway. For the settings screen, core passes its gateway list through the tutor_payment_gateways filter, which is how Tutor Pro adds its catalogue; the PayPal entry in core's Settings class shows the expected keys, including name, label, support_subscription and fields.

The gateway and config classes

GatewayBase declares three abstract methods: get_root_dir_name(), get_payment_class() and get_config_class(). Its constructor loads whatever get_autoload_file() returns, falls back to core's bundled vendor autoloader when \Brick\Money is not loaded, and builds $this->payment through PaymentHub::make(). A skeleton for a hypothetical "Acme Pay" gateway, not run on a live site; test on staging first:

namespace AcmePayTutor;

use Tutor\PaymentGateways\GatewayBase;

class AcmeGateway extends GatewayBase {
    public function get_root_dir_name(): string {
        return 'AcmePay';
    }

    public function get_payment_class(): string {
        return \AcmePayTutor\Payments\AcmePayment::class;
    }

    public function get_config_class(): string {
        return AcmeConfig::class;
    }

    public static function get_autoload_file() {
        return ''; // Return a path if the provider SDK has its own Composer autoloader.
    }
}

The config class reads the saved settings with Settings::get_payment_gateway_settings( 'acmepay' ) and overrides the getters that BaseConfig::createConfig() collects: getMode(), getSecretKey(), getPublicKey(), getWebhookSecretKey() and getName() through a $name property. Tutor Stripe also uses core's PaymentUrlsTrait, which supplies getSuccessUrl(), getCancelUrl(), getWebhookUrl() and a get_field_value() helper, so redirects and the webhook URL stay consistent with core. Implement is_configured() to return true only when every required credential is present.

The payment class contract

BasePayment has four abstract methods: setup(), check(), createPayment() and verifyAndCreateOrderData( object $payload ). Two more are expected by GatewayBase if you support them: createRecurringPayment() and createRefund(). make_refund() checks with method_exists() and throws "Refund from payment gateway is not available." when the method is absent.

The data passed to setData() for a one-time order comes from CheckoutController::prepare_payment_data(): an object with items, subtotal, total_price, order_id, a currency object, billing_address, customer and related fields. Tutor Stripe overrides setData() to branch on a type property (one-time, recurring or refund) and reshape the data for each call. Carry the Tutor order_id to the provider as metadata, because the webhook has to return it.

Webhooks and the order data you return

Core registers one public REST route for every gateway, tutor/v1/ecommerce-webhook, with the gateway key as a payment_method parameter. The handler packs $_GET, $_POST, $_SERVER and the raw request body into an object and passes it to your verifyAndCreateOrderData(). Because the route itself has no authentication, your method must verify the provider's signature before it trusts anything; Tutor Stripe calls \Stripe\Webhook::constructEvent() and accepts only an allow-list of event types.

Return the object from System::defaultOrderData( 'payment' ) with these properties filled: id (the Tutor order id), payment_status, transaction_id, payment_payload, fees and earnings. When the returned object has an id property, core fires tutor_order_payment_updated, and its handler updates the order and fires tutor_order_payment_status_changed, which drives enrolment and earnings. Return an empty stdClass for events you want to ignore. If you add a redirectUrl property, core redirects with wp_safe_redirect(). Our Stripe pending-order checklist shows what goes wrong when this path fails.

Subscriptions and refunds

Tutor Pro's subscription add-on drives renewals itself. Its SubscriptionController creates the renewal order and calls make_recurring_payment(), which prepares the data with CheckoutController::prepare_recurring_payment_data(). Tutor Stripe does not use Stripe Billing: it saves the payment method at first checkout and creates an off-session PaymentIntent for each renewal. A provider that can only bill through its own subscription objects does not fit this model without extra synchronisation work, so check this before promising subscription support. Mark the gateway with support_subscription only when createRecurringPayment() works.

Refunds started from Tutor's order screen go through OrderController to make_refund(). In Tutor Stripe 1.0.9, refund webhooks from the Stripe Dashboard are verified but not applied to Tutor orders, so refunds should be issued from Tutor.

Packaging, dependencies and upgrade risk

• Autoloading. Tutor Stripe's Composer map points Ollyo\PaymentHub\ at ../tutor/ecommerce/PaymentGateways/Paypal/src. That couples the add-on to Tutor's folder name and internal layout. A custom gateway that does the same should check on activation that Tutor is active, as Tutor Stripe does on plugins_loaded at priority 100.
• Pro dependency. Tutor Stripe requires both Tutor and Tutor Pro and reads its field list from TutorPro\Ecommerce\Config. A gateway that registers its own settings fields through tutor_payment_gateways avoids the second dependency, but you then own the settings UI contract.
• Money handling. Convert amounts to the provider's minor units and handle zero-decimal currencies. Tutor Stripe keeps a list of zero-decimal currencies and per-currency minimum charges in its Helper class.
• Upgrade testing. GatewayBase and BasePayment are internal framework classes, not a documented public API. Re-test checkout, webhook, renewal and refund on staging after every Tutor or Tutor Pro update.

When a custom gateway is worth building

Build one when your market needs a provider that Tutor's catalogue does not cover, or when finance needs fees and settlement data recorded on Tutor orders. If WooCommerce already supports the provider, compare that route first; our Tutor native e-commerce vs WooCommerce comparison covers the trade-offs. For broader provider design, including idempotent webhooks, see LMS Stripe integration. Step-by-step setup of the gateways Tutor already offers belongs on Tutor LMS Expert.

How we can help

We design and build payment gateway add-ons for Tutor LMS's native checkout, including webhook verification, renewals, refunds and upgrade test plans. See our LMS plugin development service, or contact us with your provider's API documentation.