Building and Extending Site Store Pro Payment Plugins

Site Store Pro ships with four payment processors — a test gateway and production-ready integrations for Stripe, Paddle Billing, and PayPal. You can customize the behavior of any built-in processor without touching core files by extending its class, or build an entirely new gateway by implementing the PaymentProcessorInterface contract and registering it in the platform.

Built-in Processors

ID	Name	Driver	SDK
0	Test Gateway	`TestProcessor.php`	None
1	Stripe	`StripeProcessor.php`	`stripe/stripe-php`
2	Paddle Billing	`PaddleProcessor.php`	`paddlehq/paddle-php-sdk`
3	PayPal	`PayPalProcessor.php`	Built-in HTTP client

Processor IDs 0–99 are reserved for built-in processors. When you register a custom gateway, you must use an ID of 100 or higher.

The PaymentProcessorInterface Contract

Every processor — built-in or custom — must satisfy this interface:

// app/Services/Payments/Contracts/PaymentProcessorInterface.php

interface PaymentProcessorInterface
{
    public function charge(float $amount, string $currency, array $payload): PaymentResult;
    public function isSandbox(): bool;
    public function getName(): string;
}

charge() returns a PaymentResult value object that carries the authorization code, transaction ID, success flag, and any error message back to the order processing pipeline.

Extending Built-in Processors

The cleanest way to customize a built-in processor is to extend its class. Place your extension file inside the payment-processors/ directory at the project root — the platform auto-detects extension files in that directory on boot, so you don’t need to modify any core service provider.

Stripe
Paddle
PayPal

Create payment-processors/stripe/StripeProcessorExtension.php:

<?php
namespace PaymentProcessors\Stripe;

use App\Services\Payments\Processors\StripeProcessor as BaseStripeProcessor;

class StripeProcessorExtension extends BaseStripeProcessor
{
    public function getName(): string
    {
        return 'Customized Stripe' . ($this->isSandbox() ? ' (Sandbox)' : '');
    }

    public function createPaymentIntent(float $amount, string $currency = 'usd'): array
    {
        $result = parent::createPaymentIntent($amount, $currency);
        // Add custom logging or inject metadata here
        return $result;
    }
}

Create payment-processors/paddle/PaddleProcessorExtension.php:

<?php
namespace PaymentProcessors\Paddle;

use App\Services\Payments\Processors\PaddleProcessor as BasePaddleProcessor;

class PaddleProcessorExtension extends BasePaddleProcessor
{
    public function createTransaction(
        float $amount,
        string $currency = 'USD',
        array $meta = []
    ): array {
        $meta['custom_store_ref'] = config('app.name');
        return parent::createTransaction($amount, $currency, $meta);
    }
}

Create payment-processors/paypal/PayPalProcessorExtension.php:

<?php
namespace PaymentProcessors\PayPal;

use App\Services\Payments\Processors\PayPalProcessor as BasePayPalProcessor;
use App\Services\Payments\PaymentResult;

class PayPalProcessorExtension extends BasePayPalProcessor
{
    public function charge(
        float $amount,
        string $currency,
        array $payload
    ): PaymentResult {
        // Pre- or post-process the charge here
        return parent::charge($amount, $currency, $payload);
    }
}

The platform auto-detects extension files inside payment-processors/ on boot. You don’t need to register them manually — just follow the namespace and directory naming convention shown above and the manager will pick them up.

Building a Custom Payment Gateway

Follow these nine steps to integrate a brand-new payment provider from scratch.

Custom processor IDs must be 100 or higher. IDs 0–99 are reserved for Site Store Pro’s built-in processors. Using a reserved ID will cause conflicts that are difficult to debug.

Copy the Example Gateway Template

Start from the bundled template to get the correct directory structure:

cp -r payment-processors/example-gateway payment-processors/my-gateway

Implement PaymentProcessorInterface

Create your processor class in payment-processors/my-gateway/MyGatewayProcessor.php:

<?php
namespace PaymentProcessors\MyGateway;

use App\Services\Payments\Contracts\PaymentProcessorInterface;
use App\Services\Payments\PaymentResult;

class MyGatewayProcessor implements PaymentProcessorInterface
{
    public function getName(): string
    {
        return 'My Gateway' . ($this->isSandbox() ? ' (Sandbox)' : '');
    }

    public function isSandbox(): bool
    {
        return config('services.my_gateway.sandbox', true);
    }

    public function charge(float $amount, string $currency, array $payload): PaymentResult
    {
        try {
            $transactionId = $payload['transaction_id'] ?? 'TXN_' . time();

            return new PaymentResult(
                success: true,
                authorizationCode: 'AUTH_' . rand(1000, 9999),
                transactionId: $transactionId,
                errorMessage: '',
                processorName: $this->getName()
            );
        } catch (\Throwable $e) {
            return new PaymentResult(
                success: false,
                authorizationCode: '',
                transactionId: '',
                errorMessage: $e->getMessage(),
                processorName: $this->getName()
            );
        }
    }
}

Add Environment Credentials

Add your gateway’s API keys to .env:

MY_GATEWAY_API_KEY=your_live_key
MY_GATEWAY_SANDBOX_API_KEY=your_sandbox_key

Reference these in config/services.php under a my_gateway key so they’re accessible via config('services.my_gateway.*').

Insert a Row into order_processors

INSERT INTO order_processors (processor_id, processor_name, production, created_at, updated_at)
VALUES (100, 'My Gateway', 0, NOW(), NOW());

Set production to 1 when you’re ready to accept live payments.

Load your processor file and map its ID to the class:

require_once base_path('payment-processors/my-gateway/MyGatewayProcessor.php');

$processors[100] = \PaymentProcessors\MyGateway\MyGatewayProcessor::class;

Add the Processor Type to PaymentProcessorManager

Open app/Services/Payments/PaymentProcessorManager.php and add your ID to the activeProcessorType() match expression:

return match ($this->activeProcessorId()) {
    1       => 'stripe',
    2       => 'paddle',
    3       => 'paypal',
    100     => 'my-gateway',
    default => 'test',
};

Handle Frontend Checkout Integration

Integrate your gateway’s JavaScript SDK (if applicable) inside OrderReview::preparePayment(). This method is responsible for initialising the client-side checkout flow — tokenising card data, opening a hosted payment form, or triggering a redirect to your provider’s checkout page.

Verify the Interface Contract

Double-check that your class satisfies all three methods required by PaymentProcessorInterface:

interface PaymentProcessorInterface
{
    public function charge(float $amount, string $currency, array $payload): PaymentResult;
    public function isSandbox(): bool;
    public function getName(): string;
}

PHP will throw a fatal error at runtime if any method is missing or has an incompatible signature.

Enable in the Admin Panel

Navigate to Admin → Checkout → Processors, find your new gateway in the list, and select it as the Primary processor. Toggle the sandbox flag off when you’re ready to go live.

Webhook Endpoints

Site Store Pro exposes dedicated webhook endpoints for each supported payment provider. Configure these URLs in your payment provider’s dashboard so that payment events — confirmations, subscription updates, refunds, and disputes — are pushed to your Site Store Pro installation in real time.

Method	Endpoint	Provider
`POST`	`/webhooks/stripe`	Stripe
`POST`	`/webhooks/paddle`	Paddle Billing
`POST`	`/webhooks/paypal`	PayPal

Each endpoint verifies the incoming request signature before processing the event payload:

Stripe — validates using STRIPE_WEBHOOK_SECRET (whsec_...) via Stripe’s WebhookSignatureVerifier.
Paddle — validates using PADDLE_WEBHOOK_SECRET (pwh_...) via Paddle’s notification verifier.
PayPal — validates using PAYPAL_CLIENT_ID and PAYPAL_CLIENT_SECRET to verify webhook event authenticity.

Webhook endpoints are CSRF-exempt by design — they receive POST requests from external payment providers. Ensure STRIPE_WEBHOOK_SECRET, PADDLE_WEBHOOK_SECRET, and PayPal credentials are set correctly in .env before exposing these URLs to production traffic. Missing or incorrect secrets will cause signature verification to fail and all incoming events to be rejected.

# Stripe Dashboard → Developers → Webhooks
https://yourdomain.com/webhooks/stripe

# Paddle Dashboard → Notifications
https://yourdomain.com/webhooks/paddle

# PayPal Developer Dashboard → Webhooks
https://yourdomain.com/webhooks/paypal

For local development and testing, use a tunnelling tool (such as the Stripe CLI or ngrok) to expose your local server and forward provider events to your machine before deploying to a publicly accessible URL.

Installation

Extending the Platform

Core Services

Building and Extending Site Store Pro Payment Plugins

Built-in Processors

The PaymentProcessorInterface Contract

Extending Built-in Processors

Building a Custom Payment Gateway

Webhook Endpoints

​Built-in Processors

​The PaymentProcessorInterface Contract

​Extending Built-in Processors

​Building a Custom Payment Gateway

​Webhook Endpoints

Built-in Processors

The PaymentProcessorInterface Contract

Extending Built-in Processors

Building a Custom Payment Gateway

Webhook Endpoints