SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

Portal Payment Driver Manager

Contract for registering named hosted-checkout drivers, resolving the configured portal driver, and enforcing verified receipt contract v1.

Overview

App\Services\Payments\PortalPaymentDriverManager is the customer-portal payment seam that maps a driver name such as stripe onto a concrete App\Contracts\Payments\PortalPaymentDriver implementation.

Core binds the manager as a singleton in AppServiceProvider. PortalPaymentService resolves the configured driver through it when opening a hosted checkout, and PortalPaymentWebhookController resolves the named driver when verifying an inbound provider webhook.

As a factual note about the current integration, PluginRegistrar::paymentDriver() forwards named driver registrations into this manager; this is not SDK usage guidance.

Public surface

Method Purpose
register() Add a driver class for one name; reject a different class under an occupied name
driver() Resolve a named driver or the configured default driver
has() Report whether a name is currently registered
availableDrivers() Return the currently registered driver names

Accepted contract and identity

Each registration is a pair of:

  • a string driver name
  • a class-string<App\Contracts\Payments\PortalPaymentDriver>

The manager records the class name and resolves it through the container when driver() is called. Driver implementations may therefore depend on other services through normal container construction.

The class-string<PortalPaymentDriver> requirement is a PHPDoc and static-analysis contract. register() records the class string without instantiating it, but rejects a different class under an occupied name. Container construction and runtime contract failures surface when driver() resolves a registration.

Every driver implements the complete checkout contract:

key(): string
label(): string
createCheckout(Invoice $invoice, Money $amount, string $returnUrl, string $cancelUrl, array $metadata): CheckoutRedirectData
verifyWebhook(Request $request): ?CompletedCheckoutData
  • key() is the stable machine key the driver is registered and configured under. The manager requires the registration name to equal this key.
  • label() is the human-readable name shown in settings and the portal.
  • createCheckout() receives the invoice, a Brick\Money\Money amount, the return and cancel URLs, and a array<string, string> metadata map carrying an opaque checkout-attempt ID. It must never send a bearer document token to the provider. It returns a CheckoutRedirectData describing where to send the customer.
  • verifyWebhook() returns a CompletedCheckoutData for a completion event, null when the payload is authentic but not a completion, and must throw when the signature or payload cannot be verified. The manager does not translate driver exceptions.

Required verified receipt contract

To handle payments, a driver must also implement App\Contracts\Payments\VersionedPortalPaymentDriver and return version 1 from verifiedReceiptContractVersion(). The manager refuses to select a driver without this interface or with an unsupported receipt-contract version.

Each verified completion must identify the registered provider, a non-default merchant scope, a delivery reference and event ID, an economic receipt ID, and a positive Unix receipt timestamp. It must carry a non-negative settled amount in minor units and a three-letter uppercase currency code. The webhook rejects incomplete completions before cash capture. Different events and Session/Intent aliases for one payment must carry the same economic receipt ID, so the ledger can retain each delivery without recording duplicate cash. The receipt and event IDs are each unique within provider, merchant and live/test scope; changed amount, currency, invoice, account or checkout-attempt facts are preserved as a conflict instead of overwriting the original settlement.

Optional embedded checkout

A driver may additionally implement App\Contracts\Payments\EmbeddablePortalPaymentDriver, which extends the base contract with one method:

createPaymentIntent(Invoice $invoice, Money $amount, array $metadata): PaymentIntentData
  • createPaymentIntent() receives the same invoice, Brick\Money\Money amount and array<string, string> metadata map as createCheckout(), and returns a PaymentIntentData carrying the client secret, the provider reference, and the publishable key the browser needs to mount an in-page payment form.

The embedded interface is optional. PortalPaymentService checks with instanceof and falls back to the hosted redirect. Both hosted-only and embedded drivers still need the versioned verified receipt contract. Embedded checkout additionally requires the payments.portal_checkout_mode setting to be embedded; it defaults to hosted.

Drivers implementing this interface must also decode the provider's payment-intent completion event in verifyWebhook(), returning the same CompletedCheckoutData shape as a hosted completion so that reconciliation stays unaware of which shape was used.

Current core registrations

config/payments.php currently ships with:

Name Class
stripe App\Services\Payments\Drivers\StripeCheckoutDriver
fake App\Services\Payments\Drivers\FakePortalPaymentDriver

The default selection comes from config('payments.portal_driver', 'stripe'). The testing environment defaults that config value to fake, so no test reaches a payment provider.

Default selection, availability, and collisions

The manager captures payments.drivers once, when the singleton manager is constructed. Later changes to that config key do not rebuild its private map; register() mutates the captured map directly. Driver names and their insertion order in that map are what availableDrivers() returns.

Calling driver() with no argument resolves the default configured driver:

$name ??= (string) config('payments.portal_driver', 'stripe');

Calling driver('fake') bypasses the default and resolves that named driver directly.

Unlike the driver map, payments.portal_driver is read each time driver() is called, so changing the configured default after manager construction affects the next unnamed lookup. After choosing a class, the manager asks the container on every successful lookup and does not cache driver objects itself. The container binding for that class therefore determines whether repeated lookups return transient or shared instances.

availableDrivers() returns the current registry keys. There is no extra filtering for environment support or for whether a provider is credentialed; it simply reports what has been registered. has() answers the same question for a single name and never resolves the class.

register() records drivers in an associative array keyed by name. Re-registering the same class under the same name is safe; a different class cannot replace an occupied name, including a built-in name.

Failure behaviour

If driver() cannot find the requested name, it throws InvalidArgumentException with:

Unknown portal payment driver [name].

The manager also rejects a key/name mismatch, a driver without verified receipt contract v1, or an unsupported version. It does not fall back from an unknown explicit name to the configured default, and it does not consult payments.portal_payments_enabled; that master switch is enforced by PortalPaymentService, not by driver resolution.

Current consumers

The main framework consumer is PortalPaymentService, which resolves the configured driver when opening a hosted checkout for a portal document. PortalPaymentWebhookController resolves a named driver when verifying inbound provider webhooks.

The inventory also records PluginRegistrar as a current consumer because that is how plugins register additional named drivers today.

Worked example

These are the current behaviours exercised in tests:

config(['payments.portal_driver' => 'fake']);

$default = app(PortalPaymentDriverManager::class)->driver(); // FakePortalPaymentDriver
$named = app(PortalPaymentDriverManager::class)->driver('stripe'); // StripeCheckoutDriver
$registered = app(PortalPaymentDriverManager::class)->has('stripe'); // true
$drivers = app(PortalPaymentDriverManager::class)->availableDrivers(); // ['stripe', 'fake', ...]

If the name does not exist, driver('missing-driver') throws instead of silently choosing another provider.

Shipped Stripe driver

The shipped driver creates a one-off mode: payment Stripe Checkout Session for the amount, using the Cashier-configured client. Accounts are deliberately not Cashier billables — there is no per-account Stripe customer.

Each credential resolves through App\Services\Payments\StripeCredentials: the stored setting wins, and a blank setting falls back to the Cashier config (cashier.key / cashier.secret / cashier.webhook.secret), so installs configured purely through STRIPE_* environment variables keep working unchanged.

The user-facing settings for these credentials are described in Document Portal → Stripe.

Recording a verified portal payment

On a verified webhook, immutable gross cash and its delivery event are captured before invoice allocation. The allocation then uses the ordinary RecordPayment action, with an active staff user borrowed only for authorization and a System actor recorded for attribution. If no active authorized user is available, gross cash and a durable exception remain without an invoice payment. Idempotency is keyed to the scoped economic receipt, not merely the Session reference; allocation cannot exceed the current invoice outstanding, and surplus remains unapplied on the settlement.

Registering other providers

App\Contracts\Payments\PortalPaymentDriver defines the hosted-checkout seam, while VersionedPortalPaymentDriver is required to handle payments. A driver must report verified receipt contract v1, use a stable provider key matching its registration name, and return distinct delivery/event and economic receipt identities from verifyWebhook(). Register additional drivers in config/payments.php or from a plugin with PluginRegistrar::paymentDriver(), following the contract above.