How to Build a Custom Payment Gateway for Tutor LMS

Tutor LMS native eCommerce ships with PayPal, and Tutor LMS Pro adds several more gateways. If your business needs a provider that is not on the list, such as a regional gateway or a bank's payment page, you can add it as a plugin. This guide explains how the official gateways are built, using the Tutor Stripe plugin and the built-in PayPal gateway as references.

The architecture in one picture

• Registration: a plugin adds its gateway to Tutor LMS through two filters.
• Gateway class: extends Tutor\PaymentGateways\GatewayBase and names the payment and config classes.
• Config class: reads the gateway's settings (keys, mode) and implements Ollyo\PaymentHub\Contracts\Payment\ConfigContract.
• Payment class: extends Ollyo\PaymentHub\Core\Payment\BasePayment and talks to the provider: create the payment, verify the webhook, handle refunds and, optionally, recurring payments.
• Webhook: the provider calls /wp-json/tutor/v1/ecommerce-webhook with payment_method set to your gateway; Tutor LMS hands the request to your payment class and updates the order.

Step 1: Register the gateway

This is exactly how Tutor Stripe registers itself, adapted for a gateway called mypay:

add_filter( 'tutor_gateways_with_class', function ( $value, $gateway ) {
    if ( 'mypay' === $gateway ) {
        $value['mypay'] = array(
            'gateway_class' => \MyPay\Gateway::class,
            'config_class'  => \MyPay\Config::class,
        );
    }
    return $value;
}, 10, 2 );

add_filter( 'tutor_payment_gateways_with_class', function ( $gateways ) {
    return $gateways + array(
        'mypay' => array(
            'gateway_class' => \MyPay\Gateway::class,
            'config_class'  => \MyPay\Config::class,
        ),
    );
} );

Step 2: The gateway class

GatewayBase has three abstract methods. It builds the payment object through PaymentHub and provides setup_payment_and_redirect(), verify_webhook_signature(), make_refund() and make_recurring_payment(), which call your payment class.

namespace MyPay;

use Tutor\PaymentGateways\GatewayBase;

class Gateway extends GatewayBase {
    public function get_root_dir_name(): string {
        return 'MyPay';
    }
    public function get_payment_class(): string {
        return Payment::class;
    }
    public function get_config_class(): string {
        return Config::class;
    }
    public static function get_autoload_file() {
        return ''; // or the path to your vendor/autoload.php
    }
}

Step 3: The config class

The config class extends PaymentHub's BaseConfig, uses Tutor LMS's PaymentUrlsTrait (which provides the success, cancel and webhook URLs) and returns the mode and keys. Tutor Stripe reads its saved settings with Tutor\Ecommerce\Settings::get_payment_gateway_settings( 'stripe' ); do the same with your gateway name. The ConfigContract interface requires methods such as getMode(), getSecretKey(), getPublicKey(), createConfig() and the URL getters.

Step 4: The payment class

The payment class extends BasePayment, whose abstract methods are:

• check(): bool: confirm everything needed is configured.
• setup(): void: prepare the provider's client.
• createPayment(): create the payment with the provider from the order data and redirect the buyer to pay.
• verifyAndCreateOrderData( object $payload ): object: verify the webhook signature and return the order update.

The object returned from verifyAndCreateOrderData() is how Tutor LMS learns the result. The built-in PayPal gateway fills these fields: id (the Tutor order ID you sent to the provider), payment_status (paid, failed or pending), transaction_id, fees, earnings, payment_payload and payment_method. Refunds return refund_id, refund_amount, refund_status and refund_payload. Use PayPal's implementation in tutor/ecommerce/PaymentGateways/Paypal/src/Payments/Paypal/Paypal.php as your reference.

Step 5: Settings fields

Gateways appear under Settings > Monetization > Payment Methods. The built-in ones define fields such as environment, keys, a webhook secret and the read-only webhook URL. Follow the same pattern so admins can enter your gateway's keys.

Step 6: Test thoroughly

• Successful, failed and abandoned payments.
• Duplicate webhook deliveries (the order must not be processed twice).
• Refunds and partial refunds.
• Signature verification failures.
• Currency and amount rounding.
• Subscriptions, if supported.

When the order's payment status changes, Tutor LMS fires tutor_order_payment_status_changed and completes or cancels the enrollment. Check both the order and the enrollment in every test.

Security notes

• Never trust the browser redirect alone; confirm payment from the provider's webhook or API.
• Always verify webhook signatures.
• Keep secret keys in the gateway settings, never in front-end code.

Frequently asked questions

Does this work with WooCommerce?

No. This is for Tutor LMS native eCommerce. With WooCommerce as the engine, build a WooCommerce payment gateway instead.

Is the gateway API stable across Tutor LMS versions?

It is used by Themeum's own gateways, but it is an internal API. Test your gateway with every Tutor LMS update.

Need a gateway built? Our payment gateway integration team builds and maintains them.