boboko/core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Feature: Payment resolver, Payment Provider, Completing Stripe Webhooks, Wiring Payments to checkout service

Browse Source
This commit is contained in:
arvanitakis
2026-09-03 17:27:34 +03:00
parent 35c3334690
commit 456943dc74
14 changed files with 266 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Checkout/Services/CheckoutService.php
+74 -77
View File
@@ -10,16 +10,14 @@ use Lunar\Base\Addressable;
use Lunar\DataTypes\ShippingOption;
use Lunar\Facades\ShippingManifest;
use Lunar\Models\Cart;
use Lunar\Models\Order;
use Modules\Core\Cart\Services\CartService;
use Modules\Core\Checkout\Events\BillingAddressSet;
use Modules\Core\Checkout\Events\OrderPlaced;
use Modules\Core\Checkout\Events\PaymentConfirmed;
use Modules\Core\Checkout\Events\PaymentMethodSelected;
use Modules\Core\Checkout\Events\ShippingAddressSet;
use Modules\Core\Checkout\Events\ShippingOptionSelected;
use Modules\Core\Checkout\Exceptions\InvalidShippingOptionException;
use Modules\Core\Checkout\Exceptions\UnknownPaymentTypeException;
use Modules\Core\Payment\DTOs\PaymentResult;
use Modules\Core\Payment\Models\PaymentMethod;
use Modules\Core\Payment\Services\PaymentDriverResolver;
@@ -30,9 +28,11 @@ use Modules\Core\Payment\Services\PaymentDriverResolver;
* implementation detail. See docs/checkout.md for the full design —
* Checkout is the middle of a three-stage lifecycle (Cart → Checkout →
* Order): it owns the placement moment itself (address, shipping selection,
* placeOrder()) and ends the instant an Order exists. What happens to that
* Order afterward (status transitions, fulfillment) is deliberately out of
* scope here — see OrderPlaced's docblock.
* ensuring a draft Order exists) and hands off to Payment the instant that
* draft exists — see initiatePayment(). What happens to that Order
* afterward (status transitions, fulfillment) is deliberately out of
* scope here — see docs/payments.md and Checkout\Events\OrderPlaced's
* docblock for where that now lives.
*
* Depends on CartService for cart access rather than reaching into
* Lunar\Facades\CartSession directly a second time, so Checkout stays
@@ -99,47 +99,12 @@ class CheckoutService
return $cart;
}
/**
* $fingerprint is mandatory, not optional — the caller must prove the
* cart total the shopper last saw (Cart::fingerprint()) still matches
* before an order is placed. Cart::checkFingerprint() throws Lunar's own
* FingerprintMismatchException on a mismatch (a line's price changed,
* stock adjusted the total, another tab modified the cart) rather than
* silently placing an order at a different total than what was shown.
*
* Not called directly by a storefront — see confirmPayment(), which is
* the only caller and supplies the fingerprint captured in
* selectPaymentMethod(), not one the storefront has to obtain itself.
*
* No exception wrapping: Lunar\Validation\Cart\ValidateCartForOrderCreation
* (run inside Cart::createOrder()) already throws
* Lunar\Exceptions\Carts\CartException with a field-keyed MessageBag
* ($exception->errors()) for address/shipping-option validation and the
* duplicate-order guard — already the right shape for a storefront to
* render as form errors directly. FingerprintMismatchException
* propagates the same way, for the same reason.
*
* @throws FingerprintMismatchException
* @throws CartException
*/
public function placeOrder(string $fingerprint): Order
{
$cart = $this->cart->currentOrCreate();
$cart->checkFingerprint($fingerprint);
$order = $cart->createOrder();
Event::dispatch(new OrderPlaced($order));
return $order;
}
/**
* Every payment type currently offered to the storefront — every key
* in config('lunar.payments.types') that is BOTH administratively
* enabled (Modules\Core\Payment\Models\PaymentMethod::enabled) AND
* whose registered PaymentDriver reports itself usable right now
* (PaymentDriver::isConfigured() — e.g. Stripe with no API key set is
* whose registered driver reports itself usable right now
* (Configurable::isConfigured() — e.g. Stripe with no API key set is
* never offered, regardless of the enabled toggle). A type with no
* PaymentMethod row at all (never seeded) is treated as not offered,
* same as disabled — nothing here creates one; see
@@ -167,13 +132,13 @@ class CheckoutService
* including any payment-type-specific adjustment (e.g. a COD
* surcharge), which only exists once payment_method is set and the
* cart recalculates. Captured here, server-side, rather than asked of
* the storefront: this is the last moment before confirmPayment() that
* the shopper's reviewed total is known, and confirmPayment() reads it
* the storefront: this is the last moment before initiatePayment() that
* the shopper's reviewed total is known, and initiatePayment() reads it
* back internally instead of taking a fingerprint parameter — a
* storefront should never need to know Cart::fingerprint() exists.
*
* Does not itself call a PaymentDriver — selecting a method and
* confirming payment against it are deliberately separate steps, same
* Does not itself call a payment driver — selecting a method and
* initiating payment against it are deliberately separate steps, same
* as selecting a shipping option happens before placing the order.
*
* @throws UnknownPaymentTypeException if $type isn't currently offered
@@ -200,44 +165,76 @@ class CheckoutService
}
/**
* Resolves $type's registered PaymentDriver and calls confirm() — the
* driver independently decides whether payment succeeded and, if so,
* dispatches PaymentConfirmed (see PaymentDriver's docblock) rather
* than placing the order itself or returning it here. This method is
* fire-and-forget as far as the Order is concerned: a caller that
* needs it back listens for OrderPlaced, the same way a driver's own
* post-placement step does — see PaymentConfirmed's docblock for why a
* direct return value doesn't fit every gateway (async/webhook-driven
* confirmations have no synchronous caller waiting for one at all).
* The one storefront-facing "place this order and pay for it" call —
* the point where Checkout hands off to Payment. Ensures a draft
* Order exists (Cart::createOrder() — confirmed idempotent against a
* cart's own pre-existing, not-yet-placed-at draft; see
* vendor/lunarphp/core/src/Actions/Carts/CreateOrder.php), then
* resolves the payment type selected by selectPaymentMethod() and
* calls pay() or authorize() on its driver, per that type's
* config('lunar.payments.types.{type}.capture_mode') — boboko-core's
* own types (config/payment.php) are merged into that same Lunar
* config key by PaymentServiceProvider::boot().
*
* $data carries whatever that driver needs (Stripe's payment_intent
* id, a future redirect-based provider's callback payload).
* Returns the driver's own PaymentResult UNCHANGED — this method does
* not wait for or resolve anything past what pay()/authorize() itself
* returns synchronously. A Pending result (an async gateway like
* Stripe requiring 3-D Secure/a redirect) is a normal, expected
* outcome, not an error — the caller (a storefront controller) is
* responsible for whatever the gateway needs next.
*
* The fingerprint passed to the driver is the one captured by
* selectPaymentMethod(), not supplied by the caller — see that
* method's docblock. Throws the same FingerprintMismatchException a
* caller-supplied one would if the cart's total has since changed;
* missing entirely (selectPaymentMethod() was never called for this
* cart) is treated the same as a mismatch, not a different error.
* KNOWN GAP, explicitly out of scope for now: PaymentResult alone does
* not carry gateway-specific continuation data (e.g. Stripe's
* PaymentIntent client_secret for a Pending result needing frontend
* confirmation) — that concept existed on the deleted PaymentInitiation
* DTO and was intentionally removed from Payment's abstraction layer.
* Nothing here re-introduces it; only OfflinePaymentDriver's
* always-Immediate-Succeeded path is fully wired end-to-end today.
*
* @param array<string, mixed> $data
* The draft order's own $order->total (not the Cart's) is what gets
* passed as $amount — Order::$total is Lunar's own Price-cast
* attribute, already resolving the correct Currency via the order's
* own currency_code, and is the authoritative total once the draft
* row exists.
*
* @throws UnknownPaymentTypeException if $type isn't currently offered
* (see getPaymentMethods()) — re-checked here, not just in
* selectPaymentMethod(), since a type could be disabled between
* selection and confirmation
* @throws \Lunar\Exceptions\FingerprintMismatchException
* @throws \Lunar\Exceptions\Carts\CartException
* $context passed to the driver is {cart_id, order_id} — the exact
* keys Modules\Core\Payment\Drivers\StripePaymentDriver::
* rememberIntent() already reads.
*
* Same fingerprint precondition the old placeOrder() had: mandatory,
* not optional, checked before the draft is created.
*
* @param array<string, mixed> $data passed through untouched to
* the driver's pay()/authorize() — e.g. Stripe's payment_method
* token.
*
* @throws UnknownPaymentTypeException if the cart's selected
* payment_method (from selectPaymentMethod()) is no longer offered
* — re-checked here, not just at selection time, since a type could
* be disabled in between
* @throws FingerprintMismatchException
* @throws CartException
*/
public function confirmPayment(string $type, array $data = []): void
public function initiatePayment(string $fingerprint, array $data = []): PaymentResult
{
if (! in_array($type, $this->getPaymentMethods(), true)) {
throw new UnknownPaymentTypeException($type);
$cart = $this->cart->currentOrCreate();
$cart->checkFingerprint($fingerprint);
$type = $cart->meta['payment_method'] ?? null;
if ($type === null || ! in_array($type, $this->getPaymentMethods(), true)) {
throw new UnknownPaymentTypeException((string) $type);
}
$cart = $this->cart->currentOrCreate();
$fingerprint = $cart->meta['checkout_fingerprint'] ?? '';
$order = $cart->createOrder();
$this->paymentDrivers->resolve($type)->confirm($cart, $type, $fingerprint, $data);
$driver = $this->paymentDrivers->resolve($type);
$captureMode = config("lunar.payments.types.{$type}.capture_mode", 'pay');
$context = ['cart_id' => $cart->id, 'order_id' => $order->id];
return $captureMode === 'authorize'
? $driver->authorize($type, $order->total, $data, $context)
: $driver->pay($type, $order->total, $data, $context);
}
}