┌────────────────────────────────────────────────────────────────┐
│  PaymentGatewayManager           (Laravel Manager)             │
│  ├─ resolves drivers by code or Gateway model                  │
│  ├─ exposes getDriverManifest() for the gateway picker UI      │
│  └─ accepts third-party drivers via extend()                   │
└────────────────────────────────────────────────────────────────┘
                       │ resolves
                       ▼
┌────────────────────────────────────────────────────────────────┐
│  GatewayDriverInterface          (the contract)                │
│  └─ AbstractGatewayDriver        (base class with helpers)     │
│      └─ YourCustomDriver         ← what you'll build           │
└────────────────────────────────────────────────────────────────┘
                       │ uses
                       ▼
┌────────────────────────────────────────────────────────────────┐
│  PurchaseRequest │ RefundRequest │ GatewayResponse  (DTOs)     │
└────────────────────────────────────────────────────────────────┘
                       │ webhooks land at
                       ▼
┌────────────────────────────────────────────────────────────────┐
│  POST /ledger/webhooks/{driver}  → WebhookController           │
│  ├─ resolves the driver, calls handleWebhook()                 │
│  ├─ persists a GatewayTransaction (idempotency key)            │
│  └─ dispatches PaymentSucceeded / RefundProcessed events       │
└────────────────────────────────────────────────────────────────┘

<?php

namespace MyCompany\Ledger\Gateways;

use Fleetbase\Ledger\DTO\GatewayResponse;
use Fleetbase\Ledger\DTO\PurchaseRequest;
use Fleetbase\Ledger\DTO\RefundRequest;
use Fleetbase\Ledger\Exceptions\WebhookSignatureException;
use Fleetbase\Ledger\Gateways\AbstractGatewayDriver;
use GuzzleHttp\Client;
use Illuminate\Http\Request;

class PaypalDriver extends AbstractGatewayDriver
{
    private const HOST_PRODUCTION = 'https://api-m.paypal.com';
    private const HOST_SANDBOX    = 'https://api-m.sandbox.paypal.com';

    protected ?Client $client = null;

    public function getName(): string
    {
        return 'PayPal';
    }

    public function getCode(): string
    {
        return 'paypal';
    }

    public function getCapabilities(): array
    {
        return ['purchase', 'refund', 'webhooks', 'sandbox'];
    }

    public function getConfigSchema(): array
    {
        return [
            [
                'key'      => 'client_id',
                'label'    => 'Client ID',
                'type'     => 'text',
                'required' => true,
                'hint'     => 'Your PayPal REST app client ID.',
            ],
            [
                'key'      => 'client_secret',
                'label'    => 'Client Secret',
                'type'     => 'password',
                'required' => true,
                'hint'     => 'Your PayPal REST app secret. Never expose publicly.',
            ],
            [
                'key'      => 'webhook_id',
                'label'    => 'Webhook ID',
                'type'     => 'text',
                'required' => false,
                'hint'     => 'PayPal Webhook ID, used to verify signatures.',
            ],
        ];
    }

    public function initialize(array $config, bool $sandbox = false): static
    {
        parent::initialize($config, $sandbox);

        $this->client = new Client([
            'base_uri'    => $sandbox ? self::HOST_SANDBOX : self::HOST_PRODUCTION,
            'http_errors' => false,
            'headers'     => ['Accept' => 'application/json'],
        ]);

        return $this;
    }

    // purchase(), refund(), handleWebhook() implemented below…
}

public function purchase(PurchaseRequest $request): GatewayResponse
{
    try {
        $token = $this->fetchAccessToken();

        $response = $this->client->post('/v2/checkout/orders', [
            'headers' => ['Authorization' => "Bearer {$token}"],
            'json'    => [
                'intent'         => 'CAPTURE',
                'purchase_units' => [[
                    'amount' => [
                        'currency_code' => $request->currency,
                        'value'         => number_format($request->amount / 100, 2, '.', ''),
                    ],
                    'description' => $request->description,
                    'custom_id'   => $request->invoiceUuid,
                ]],
                'application_context' => [
                    'return_url' => $request->returnUrl ?? url('/'),
                    'cancel_url' => $request->cancelUrl ?? url('/'),
                ],
            ],
        ]);

        $body = json_decode((string) $response->getBody(), true);

        if ($response->getStatusCode() >= 400) {
            return GatewayResponse::failure(
                eventType: GatewayResponse::EVENT_PAYMENT_FAILED,
                message:   $body['message'] ?? 'PayPal order creation failed.',
                errorCode: $body['name'] ?? null,
                rawResponse: $body ?? [],
            );
        }

        // For redirect flows, return pending and surface the approve URL on $data.
        $approveUrl = collect($body['links'] ?? [])
            ->firstWhere('rel', 'approve')['href'] ?? null;

        $this->logInfo('PayPal order created', [
            'id'     => $body['id'] ?? null,
            'amount' => $request->amount,
        ]);

        return GatewayResponse::pending(
            gatewayTransactionId: $body['id'],
            eventType:   GatewayResponse::EVENT_PAYMENT_PENDING,
            message:     'Order created. Awaiting customer approval.',
            rawResponse: $body,
            data: [
                'order_id'    => $body['id'],
                'approve_url' => $approveUrl,
            ],
        );
    } catch (\Throwable $e) {
        $this->logError('PayPal purchase failed', ['error' => $e->getMessage()]);

        return GatewayResponse::failure(
            eventType: GatewayResponse::EVENT_PAYMENT_FAILED,
            message:   $e->getMessage(),
        );
    }
}

public function refund(RefundRequest $request): GatewayResponse
{
    try {
        $token = $this->fetchAccessToken();

        // PayPal refunds against a capture ID. The capture ID was stored as the
        // gatewayTransactionId by handleWebhook() when the payment was completed.
        $response = $this->client->post(
            "/v2/payments/captures/{$request->gatewayTransactionId}/refund",
            [
                'headers' => ['Authorization' => "Bearer {$token}"],
                'json'    => [
                    'amount' => [
                        'currency_code' => $request->currency,
                        'value'         => number_format($request->amount / 100, 2, '.', ''),
                    ],
                    'note_to_payer' => $request->reason,
                ],
            ],
        );

        $body = json_decode((string) $response->getBody(), true);

        if ($response->getStatusCode() >= 400) {
            return GatewayResponse::failure(
                eventType:   GatewayResponse::EVENT_REFUND_FAILED,
                message:     $body['message'] ?? 'Refund failed.',
                errorCode:   $body['name'] ?? null,
                rawResponse: $body ?? [],
            );
        }

        $this->logInfo('PayPal refund created', ['id' => $body['id'] ?? null]);

        return new GatewayResponse(
            successful:           true,
            gatewayTransactionId: $body['id'],
            status:               GatewayResponse::STATUS_REFUNDED,
            eventType:            GatewayResponse::EVENT_REFUND_PROCESSED,
            message:              'Refund processed successfully.',
            amount:               $request->amount,
            currency:             $request->currency,
            rawResponse:          $body,
        );
    } catch (\Throwable $e) {
        $this->logError('PayPal refund failed', ['error' => $e->getMessage()]);

        return GatewayResponse::failure(
            eventType: GatewayResponse::EVENT_REFUND_FAILED,
            message:   $e->getMessage(),
        );
    }
}

public function handleWebhook(Request $request): GatewayResponse
{
    $payload = $request->getContent();
    $headers = $request->headers->all();

    // 1. Verify the signature.
    if (!$this->verifyWebhookSignature($payload, $headers)) {
        throw new WebhookSignatureException('paypal', 'Signature verification failed.');
    }

    $event = json_decode($payload, true);
    $type  = $event['event_type'] ?? '';

    // 2. Map the gateway's event types to Ledger's normalized event constants.
    [$normalizedEvent, $status] = match ($type) {
        'PAYMENT.CAPTURE.COMPLETED' => [
            GatewayResponse::EVENT_PAYMENT_SUCCEEDED,
            GatewayResponse::STATUS_SUCCEEDED,
        ],
        'PAYMENT.CAPTURE.DENIED', 'PAYMENT.CAPTURE.DECLINED' => [
            GatewayResponse::EVENT_PAYMENT_FAILED,
            GatewayResponse::STATUS_FAILED,
        ],
        'PAYMENT.CAPTURE.REFUNDED' => [
            GatewayResponse::EVENT_REFUND_PROCESSED,
            GatewayResponse::STATUS_REFUNDED,
        ],
        default => [
            GatewayResponse::EVENT_UNKNOWN,
            GatewayResponse::STATUS_PENDING,
        ],
    };

    // 3. Pull the resource ID and amount from the event payload.
    $resource     = $event['resource'] ?? [];
    $referenceId  = $resource['id'] ?? $event['id'] ?? '';
    $amountValue  = $resource['amount']['value']         ?? null;
    $currency     = $resource['amount']['currency_code'] ?? null;
    $amountMinor  = $amountValue !== null ? (int) round(((float) $amountValue) * 100) : null;

    $this->logInfo('Webhook received', [
        'paypal_event'     => $type,
        'normalized_event' => $normalizedEvent,
        'resource_id'      => $referenceId,
    ]);

    return new GatewayResponse(
        successful:           in_array($normalizedEvent, [
            GatewayResponse::EVENT_PAYMENT_SUCCEEDED,
            GatewayResponse::EVENT_REFUND_PROCESSED,
        ], true),
        gatewayTransactionId: $referenceId,
        status:               $status,
        eventType:            $normalizedEvent,
        message:              "PayPal event: {$type}",
        amount:               $amountMinor,
        currency:             $currency,
        rawResponse:          $event,
        data: [
            // If you can resolve the invoice from the webhook, include it on $data
            // so the listener can mark the invoice paid without a second lookup.
            'invoice_uuid' => $resource['custom_id'] ?? null,
        ],
    );
}

public function getCapabilities(): array
{
    return ['purchase', 'refund', 'webhooks', 'sandbox', 'tokenization'];
}

public function createPaymentMethod(array $data): GatewayResponse
{
    // Call the gateway's tokenization API and return a token reference in
    // gatewayTransactionId. The token can be passed back in
    // PurchaseRequest::$paymentMethodToken on a future purchase.
    // …
}

<?php

namespace MyCompany\Ledger;

use Fleetbase\Ledger\PaymentGatewayManager;
use Illuminate\Support\ServiceProvider;
use MyCompany\Ledger\Gateways\PaypalDriver;

class PaypalServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $this->app->resolving(PaymentGatewayManager::class, function ($manager) {
            $manager->extend('paypal', fn ($app) => $app->make(PaypalDriver::class));
        });
    }
}

POST /ledger/webhooks/{driver}

public function initialize(array $config, bool $sandbox = false): static
{
    parent::initialize($config, $sandbox);

    $this->client = new Client([
        'base_uri' => $sandbox ? self::HOST_SANDBOX : self::HOST_PRODUCTION,
        // …
    ]);

    return $this;
}