Laravel Cashier Nets Laravel Package

Getting Started

Upgrade to v1.5.0 normally; there are no schema, migration, config, or dependency changes called out. The first place to look is the Subscription model/class and the recordCheckoutCharge() implementation, plus the shared checkout/webhook transaction finalization path and the ChargeSucceeded event/listener wiring.

The first practical use case is recovering a captured initial checkout payment when the charge webhook was missed. Fetch the captured provider charge, then record it against the subscription so the local transaction exists and can be refunded through the package’s normal transaction/refund flow:

use Illuminate\Support\Carbon;

$subscription = Subscription::findOrFail($subscriptionId);

$transaction = $subscription->recordCheckoutCharge([
    'provider' => 'stripe',
    'provider_charge_id' => $chargeId,
    'amount' => 4900,
    'currency' => 'usd',
    'charge' => $capturedChargePayload, // full-charge evidence
    'captured_at' => Carbon::parse($capturedAt),
]);

Confirm the exact argument names and payload shape in the package source/docs. Treat the above as the integration shape: provider identity, amount, currency, full-charge evidence, and capture timestamp are required.

Implementation Patterns

• Use webhooks as the primary path and recordCheckoutCharge() as the reconciliation/fallback path. A scheduled job can scan checkout charges that have no local transaction and record them.
• Use it for the initial checkout charge only. Do not use it for renewals, unrelated charges, or refunds.
• Make reconciliation idempotent around the provider charge identity. Check for an existing local transaction before calling, and rely on the package’s shared transaction creation/finalization behavior to avoid duplicate state.
• Keep ChargeSucceeded listeners idempotent. Use them for provisioning, receipts, analytics, or notifications, but do not manually dispatch ChargeSucceeded after recording.
• If you need listener failures to roll back local recording, keep the critical listener synchronous. Queued listeners run later and cannot roll back a transaction that already committed.
• After recording, use the returned transaction with the package’s normal refund APIs. The point of the feature is to make the transaction locally available even when the original charge webhook is missing.
• Do not manually adjust the subscription’s mandate lifecycle or renewal schedule after recording. The method is intended to preserve both.
• In tests, assert that: the transaction is created/finalized, the subscription renewal schedule is unchanged, ChargeSucceeded is emitted once for a successful recording, and a throwing listener rolls back local recording for retry.

Example reconciliation command shape:

foreach ($missingCheckoutCharges as $charge) {
    $subscription = Subscription::findOrFail($charge->subscription_id);

    if ($subscription->transactions()->where('provider_charge_id', $charge->id)->exists()) {
        continue;
    }

    $subscription->recordCheckoutCharge([
        'provider' => $charge->provider,
        'provider_charge_id' => $charge->id,
        'amount' => $charge->amount,
        'currency' => $charge->currency,
        'charge' => $charge->provider_payload,
        'captured_at' => $charge->captured_at,
    ]);
}

Gotchas and Tips

• Required evidence matters: provider identity, amount, currency, full-charge evidence, and capture timestamp must all be present and valid. Partial provider payloads are likely to fail validation.
• Use the package’s expected money format for amount and currency. Avoid floats; minor-unit integers are typical for billing packages.
• This records a captured initial checkout payment. Do not use it to “fix” renewals or arbitrary charges.
• The package preserves terminal outcomes. Do not force a charge into a different terminal state after recording; let the shared finalization path do its job.
• ChargeSucceeded should be emitted once for a successful recording. If a listener throws, local recording rolls back so retry is possible, but any external side effects already performed by that listener are not rolled back. Design listeners defensively.
• Watch queued listeners: they are useful for non-critical work, but they do not participate in the recording transaction’s rollback behavior.
• Debug by logging the provider charge ID, amount, currency, capture timestamp, existing transaction lookup, and the exact listener exception. A failed recording is often a validation/evidence mismatch or a listener exception, not a schema issue.
• There are no schema or dependency changes in v1.5.0, so missing migrations are not the cause of failures. Check provider payload completeness, method arguments, and event listeners first.
• Extension point: implement a reconciliation command/service around recordCheckoutCharge(), and keep business reactions in idempotent ChargeSucceeded listeners rather than duplicating transaction creation logic.