Skip to main content

​
Custom Gateways

Subscribd’s gateway system is driver-based. If none of the built-in gateways fit your needs, implement the Gateway contract and register your driver in config.

​
Implement the Gateway contract

<?php

namespace App\Billing\Gateways;

use Pixelworxio\Subscribd\Contracts\Billable;
use Pixelworxio\Subscribd\Contracts\Gateway;
use Pixelworxio\Subscribd\Models\Invoice;
use Pixelworxio\Subscribd\Models\Plan;
use Pixelworxio\Subscribd\Models\Subscription;
use Pixelworxio\Subscribd\Enums\CheckoutMode;

class MyGateway implements Gateway
{
    public function createSubscription(Billable $billable, Plan $plan, array $options = []): Subscription
    {
        // Create the subscription at your payment provider
        // Return the local Subscription model
    }

    public function cancelSubscription(Subscription $subscription, bool $immediately = false): Subscription
    {
        // Cancel at the provider
        // Return the updated Subscription model
    }

    public function updateSubscription(Subscription $subscription, array $options = []): Subscription
    {
        // Update quantity, plan, or other attributes
    }

    public function createInvoice(Billable $billable, array $lineItems, array $options = []): Invoice
    {
        // Create a one-off invoice
    }

    public function retryInvoice(Invoice $invoice): Invoice
    {
        // Retry a failed invoice
    }

    public function createCustomer(Billable $billable, array $options = []): string
    {
        // Create a customer record at the provider
        // Return the provider's customer ID string
    }

    public function checkoutMode(): CheckoutMode
    {
        // Return CheckoutMode::Hosted, CheckoutMode::Embedded, or CheckoutMode::Overlay
        return CheckoutMode::Hosted;
    }

    public function createHostedCheckoutSession(Billable $billable, Plan $plan, array $options = []): string
    {
        // Return the URL the user should be redirected to for checkout
    }

    public function supportsNativeProration(): bool
    {
        return false;
    }

    public function supportsTrialExtension(): bool
    {
        return false;
    }

    public function supportsPause(): bool
    {
        return false;
    }
}
The DefaultGatewayCapabilities concern provides no-op implementations for optional capability methods. Use it as a starting point: 
use Pixelworxio\Subscribd\Concerns\DefaultGatewayCapabilities;

class MyGateway implements Gateway
{
    use DefaultGatewayCapabilities;

    // Only implement the methods your provider actually supports
}

​
Register your gateway

Add it to config/subscribd.php: 
'gateways' => [
    'my_gateway' => [
        'driver'     => \App\Billing\Gateways\MyGateway::class,
        'api_key'    => env('MY_GATEWAY_API_KEY'),
        'api_secret' => env('MY_GATEWAY_API_SECRET'),
    ],
],
You can access your gateway config inside the driver class via config('subscribd.gateways.my_gateway').

​
Set as the default

'default' => env('SUBSCRIBD_GATEWAY', 'my_gateway'),
Or use it per-subscription: 
app(CreateSubscription::class)->execute($user, $plan, ['gateway' => 'my_gateway']);

​
Handling webhooks

Register a webhook controller and route it through Subscribd’s webhook pipeline by creating an event handler for your gateway’s events: 
// routes/webhooks.php (auto-loaded by Subscribd)
// The webhook endpoint is at /subscribd/webhook/{gateway}
// Subscribd calls your gateway's handleWebhook() method automatically
Implement handleWebhook(Request $request): Response on your gateway class to process incoming webhook payloads and dispatch the appropriate Subscribd events (SubscriptionCreated, SubscriptionUpdated, etc.).

​
Next steps