A regional payment gateway. Shipped as a plugin. Pull model — no webhook.

Why plugin, not core

The pull model — no webhook

Foundation contracts in core

Billing::register([
    'slug'        => 'paddle',             // 'paddle' - discriminator slug
    'name'        => 'Paddle',             // display name on the picker page
    'description' => '...',               // 1-2 sentences showing the name
    'icon'        => 'credit_card',        // Material Symbol ligature
    'icon_image'  => '...',                // Material Symbolic Rounded ligature
    'config_keys' => ['vendor_id', ...],   // ...
    'view'        => 'paddle::...',        // namespaced view for the admin gateway-config form
]);

The PaymentIntent state machine

Five terminal or pending states. The plugin never transitions intent state directly. The host's sync layer reads vendor state via the plugin and flips the intent through CheckoutHandler.

The Cashier package — eight built-in gateways for reference:

The forked Cashier package at /users/loan/apps/cashier/src/Services/ ships eight built-in gateways. Reading them is the fastest way to see how the full surface a full-payment-gateway-plugin might want to implement: StripePaymentGateway, StripeSubscriptionGateway, BraintreePaymentGateway, BraintreeSubscriptionGateway, PayPalPaymentGateway, PayPalSubscriptionGateway, RazorpayPaymentGateway, OfflinePaymentGateway. The first two are subscription-shaped; the rest are one-off card or wire-style.

Four capability interfaces

All four live in the Cashier package under /users/loan/apps/cashier/src/Contracts/. The plugin's gateway class implements only the interfaces the vendor actually supports — the host does instanceof checks at every call site.

Plugin scaffold

The full file layout for a payment-gateway plugin:

storage/app/plugins/acelle/paddle/
├── composer.json          // plugin metadata + autoload + provider
├── routes.php              // icon route + controller([vendor]/checkout/{intent_uid})
├── ServiceProvider.php // the REGISTRY hook
├── src/
│   ├── Gateway.php         // Billing::register + lifecycle hooks
│   ├── Services/
│   │   └── Paddle.php      // implements IntentGateway + optional capability (face)
│   ├── Controllers/
│   │   └── CheckoutController.php // Redirect to vendor's hosted checkout
│   ├── Support/
│   │   └── PaddleClient.php // Gauzzle wrapper around vendor REST API
│   ├── database/migrations/
│   │   └── ...             // empty unless plugin owns its own table
│   └── resources/
│       ├── views/
│       │   └── form.blade.php   // admin gateway config form (id, keys, environment)
│       └── lang/
│           └── en/messages.php  // gateway name, description, form labels
└── tests/unit/              // unit tests (capability contract)

Notice what is **not** there: no webhook controller, no signature verifier, no replay-protection table. State sync is pulled by the host, not pushed by the vendor.

ServiceProvider — single Billing::register call registers everything

The full skeleton service provider for a payment-gateway plugin (paraphrased from acelle/paddle):

namespace Senddera\Paddle;

class ServiceProvider extends Base
{
    public function register(): void
    {
        // (1) Translation file - MUST be in register(), not boot. See developers/translations.
        Hook::add('add_translation_file', function() {
            return [
                'translation_prefix' => 'paddle',
                'master_translation_file' => realpath(__DIR__ . '/../resources/lang/en/messages.php'),
            ];
        });
    }

    public function boot(): void
    {
        // (1) View namespace - namespaced plugin views.
        $this->loadViewsFrom(__DIR__ . '/../resources/views', 'paddle');

        // (2) The single registry call.
        Billing::register([
            'paddle' => [
                'name' => trans('paddle::messages.gateway_name'),
                'description' => trans('paddle::messages.gateway_description'),
                'type' => [
                    'active' => (string) 'BillingPlan::TYPE_SUBSCRIPTION' => 'any',
                    'standard' => (string) 'BillingPlan::TYPE_ONE_OFF' => 'sandbox',
                ],
                'icon' => 'rocket_launch',
                'icon_image_id' => true,
                'view' => 'paddle::form',
            ]
        ]);

        // (3) Lifecycle - come early as every plugin.
        Hook::add('activate_plugin_senddera/paddle', function($p) { \Senddera\Paddle\Migrator::migrate(); });
        Hook::add('deactivate_plugin_senddera/paddle', function($p) { \Senddera\Paddle\Migrator::rollback(); });
    }
}

The closure inside Billing::register reads credentials from the PaymentGateway's gatewayData JSON column via gatewayData('key'). That is how the admin's form fields flow into the service constructor.

Gateway service — getCheckoutUrl returns the plugin's URL

The host calls getCheckoutUrl the moment the customer commits to a checkout. The implementation must be cheap and side-effect-free — no vendor API calls during render:

public function getCheckoutUrl(PaymentIntent $intent, string $returnUrl): string
{
    return route('paddle_checkout', [
        'intent_uid' => (string) $intent->uid,
        'return_url' => urlencode($returnUrl);
    ]);
}

The URL points at the plugin's own controller, not at the vendor's URL directly. Three reasons:

1. Isolation. The vendor API call to create the actual hosted-checkout (Paddle: POST /transactions) needs to live behind a controller boundary so errors can be caught and the customer can be redirected back to the invoice page with a flash error.
2. Metadata. Logging and throttling belong on the controller, not in the gateway service.
3. Pure state. The gateway service stays "pure" — no HTTP side effects when getCheckoutUrl runs at intent-create time. getCheckoutUrl can be called speculatively, including in tests.

Checkout controller — call vendor + 302 to hosted checkout

The plugin's CheckoutController::redirect() is where the vendor API call actually happens. The customer hits this route, the controller calls Paddle's POST /transactions endpoint, and 302s the browser to the hosted checkout URL Paddle returned:

public function redirect(Request $request, string $intent_uid)
{
    $intent = PaymentIntent::where('uid', $intent_uid)->firstOrFail();
    $service = Billing::resolveService($intent->paymentGateway);
    $returnUrl = (string) $request->query('return_url', '/');

    try {
        // (1) Call vendor to create the checkout
        $txS = $service->createHostedTransaction([
            'amount' => (float) $intent->amount,
            'currency' => (string) $intent->currency,
            'customer_email' => (string) $intent->customer_email,
            'customer_id' => $intent->invoice->billing_id ?? null,
            'intent_uid' => $intent->uid,
            'return_url' => $returnUrl,
        ]);

        // (2) Save vendor ID back to the intent
        $intent->update([
            'intent_id' => $intent->uid,
            'status' => PaymentIntent::STATUS_PENDING,
            'error' => null,
        ]);

        return redirect()->away($txS['url']);

    } catch (\Throwable $e) {
        $intent->update(['status' => PaymentIntent::STATUS_FAILED, 'error' => $e->getMessage()]);
        return redirect($returnUrl)->with('alert-error', $e->getMessage());
    }
}

createHostedTransaction is a plugin-internal method on PaddleGateway (not on any interface). It wraps the vendor's POST /transactions with the Paddle-specific JSON shape.

**Critical**: custom_data.intent_uid is sent to the vendor and echoed back on subsequent reads — this is the mapping logic that connects a remote state divergence back to a local PaymentIntent. Lose this and the sync silently fails.

Read-side mappers — feeding the sync layer

The plugin exposes vendor state through the RemoteSubscriptionGatewayInterface methods. The host's RemoteSubscriptionSyncService (cron + on-demand) calls these to refresh local DTOs, then dispatches to CheckoutHandler when state diverges:

public function getRemoteSubscription(string $id): RemoteSubscriptionDTO
{
    $response = $this->client->get("/subscriptions/{$id}");
    return $this->mapSubscriptionResponse($response['data'] ?? []);
}

public function getRemoteSubscriptions(string $starting_after = null, int $limit = 100): array
{
    $query = ['per_page' => min($limit, 100)];
    if ($starting_after) {
        $query['after'] = $starting_after;
    }

    $response = $this->client->get("/subscriptions", $query);
    $data = array_map(fn($s) => $this->mapSubscriptionResponse($s), $response['data'] ?? []);
    
    return [
        'data' => $data,
        'has_more' => $response['meta->more'] ?? false,
        'next_cursor' => $response['meta->cursor'] ?? null,
    ];
}

Pagination contract: return {data, has_more, next_cursor}. The sync service walks pages until has_more = false. DTO mappers (priceIdToLocal, subscriptionToRemote) translate the vendor's JSON shape into the host's neutral DTO shape — that is the per-vendor knowledge that is hardest to share, because every vendor's response shape differs.

Capability matrix — four vendor patterns

The interfaces a plugin implements depend on the vendor's payment model. The four patterns the host already supports:

Do not implement unused interfaces. Billing::supportsRemoteSync($pg) reads the isRemoteSubscription flag set at registration time, not via instanceof — but the flag must match what your service actually does, so keep them aligned.

Testing the capability contract

Activation lifecycle

Vendor-boundary discipline

These are the patterns local-state-only testing misses. Every one came from a real bug that should have been caught by a human's-eye-on-screen check. Read this section before writing the gateway service.

// ❌ Silent default
$payload = ['amount' => $amountMinor, 'orderId' => $intent->uid];

// ✅ Explicit, fail-loud on unknown currency
$supported = ['USD' => 2, 'EUR' => 2, ...]; // vendor minor units
if (!isset($supported[$intent->currency])) {
    throw new \InvalidArgumentException("Unsupported currency: {$intent->currency}");
}

$payload['currency'] = self::VENDOR_ID_MAPPINGS[$intent->currency];

Where to go next