> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subscribd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Gateways

> Build a custom payment gateway driver for Subscribd

# 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 theme={null}
<?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:

```php theme={null}
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`:

```php theme={null}
'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

```php theme={null}
'default' => env('SUBSCRIBD_GATEWAY', 'my_gateway'),
```

Or use it per-subscription:

```php theme={null}
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:

```php theme={null}
// 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

* **[Hooks and Events](/advanced/hooks-and-events)** — Events your gateway should dispatch
* **[Testing](/advanced/testing)** — Test your gateway with FakeGateway patterns