Skip to content

Move checkout onto Lunar 2.0.0-alpha.9 split packages - #9

Merged
alecritson merged 32 commits into
mainfrom
lunar-alpha-9
Nov 12, 2026
Merged

alecritson merged 32 commits into
mainfrom
lunar-alpha-9

Conversation

@alecritson

@alecritson alecritson commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Why

The checkout package listed lunarphp/lunarmono (dev-checkout-deps) in its main require, so every app that installs checkout had to pull the Lunar monorepo from GitHub. That is why Edwardes and KJP carry a dev-edw-deps as dev-checkout-deps alias. Checkout was also written against a pre-release payment intent API that changed shape before alpha.8. This PR moves checkout onto the released Lunar 2.0.0-alpha.9 split packages and adapts it to the breaking changes, so the apps can drop the monorepo. Linear: EDW2-227 (epic EDW2-225).

What changed

Composer. lunarphp/lunarmono and the lunarphp/lunar VCS repository are gone. lunarphp/core stays at ^2.0@dev. lunarphp/panel, lunarphp/stripe and lunarphp/table-rate-shipping are require-dev at ^2.0@alpha. Everything resolves from Packagist.

Payment intents (#2746, #2750).

  • Checkout types against ReconcilesPaymentIntents. Every intent verb takes the session's cart first, and amounts are PriceValue.
  • Refund and capture amounts use the session's pinned currency, not the cart's current one.
  • Holds are read from fetchIntent() snapshots, because describeHold() is gone.
  • The client secret comes from clientPayload['client_secret']. The JSON response keeps the intent and clientSecret keys.
  • RequiresAction and Processing both reconcile as pending. Alpha.9 Stripe also reports a declined card as RequiresAction, so once a session has waited on the customer longer than lunar.checkout.reconciliation.requires_action_minutes (default 30), its intent is voided and the session reopens. Without this, a decline followed by a closed tab locks the cart for good. If the void is refused because the payment went through in the meantime, the session stays pinned and the next pass completes it.
  • A customer who comes back from a failed redirect payment (redirect_status=failed for the session's own intent) has their session released at once, on the gateway's word that nothing was captured.
  • Reconcile reads the snapshot's refunded amount. A fully refunded intent finishes the earlier refund without calling refund again, and is never completed. A partial refund stalls to the operator.
  • The gateway success listener records which order the gateway placed for the session's intent. Reconcile never refunds that order, even when the listener pinned the session after the order was placed.
  • At pay, a hold or intent the gateway refuses to resize gets a 422 the client already handles, instead of a 500.
  • authorize() receives the intent under both reference (the key core documents) and payment_intent.
  • Reconcile, release and invalidation load the cart withTrashed(), so money on a pruned cart can still be voided or refunded.

Steps registry (#2792). PickupPointRequired is registered with Steps::for(StepList::OrderCreateValidation)->append(...). Checkout no longer writes lunar.cart.validators, which core now rejects with RemovedStepConfigException.

Pickup rename (#2717). Checkout reads ShippingOption::$pickup and the order line's meta['pickup']. The package's own collect mode string, its JSON key and the customer-facing copy are unchanged.

Fresh totals (#2721). Core caches cart totals, so every money path now uses recalculate():

  • intent and hold creation
  • the pay pin
  • the fingerprint
  • the completion check
  • availability gating at pay
  • the webhook listener's snapshot

Related changes:

  • The session's cart eager-loads lines.purchasable. Cached totals skip the pipeline's eager load, and table-rate shipping then lazy-loads purchasables.
  • The gateway success listener now takes its snapshot before it locks the session row. That keeps the lock order the same as the pay gate.

Tests and docs.

  • Tests use the array mailer, because core now sends order emails.
  • The spec docs use the alpha.9 names.

Consumer impact

  • The apps can alias "lunarphp/checkout": "dev-lunar-alpha-9 as 2.0.0-alpha.1" and drop lunarmono.
  • The apps must require lunarphp/stripe themselves, because checkout lists it only in require-dev.
  • The apps must delete any lunar.cart.validators config. Core throws while it exists.
  • There is one new optional config key: lunar.checkout.reconciliation.requires_action_minutes.
  • These are unchanged: routes, events, failure reason strings, and the clientSecret and collect JSON keys.

Testing

The suite runs with vendor/bin/pest --testsuite checkout and gives 398 passed, 1 skipped. The skip was already on main: it needs the published build. phpstan and pint are clean. New tests cover these cases:

  • A price change after the basket was calculated: the intent, the pin and the completion check all use the new total.
  • Both RequiresAction and Processing reconcile as pending.
  • A RequiresAction intent past the window reopens.
  • Refunds use the pinned currency.
  • Operator refunds work on pruned carts.
  • The Steps registration.
  • Multi-line carts under preventLazyLoading.

…repo

Drop lunarphp/lunarmono from require and the lunarphp/lunar VCS
repository, so consuming apps no longer have to install the monorepo.
Tests pull lunarphp/panel, lunarphp/stripe and
lunarphp/table-rate-shipping from Packagist at ^2.0@alpha.

Remove the README advice to test against a local path repository,
since core is now released on Packagist.
Lunar 2.0.0-alpha.9 replaced SupportsPaymentIntents with
ReconcilesPaymentIntents. fetchIntent, voidIntent and refundIntent now
take the Cart first, fetchIntent returns a nullable
PaymentIntentSnapshot, and a refund amount is a PriceValue.

Load the session's cart at each call site and pass it through. A cart
that no longer exists, or a null snapshot (the driver did not create
the reference for that cart), is an unknowable outcome: reconcile
counts an attempt, release answers `unconfirmed`, and invalidation
refuses to cancel.

CreatesPaymentIntents now extends the reconciliation contract, so the
test gateways that only create intents gain verbs that throw, which
keeps their sessions unresolved as before.

The Pending status and the hold calls follow in their own commits.
…nding

Core split PaymentIntentStatus::Pending into RequiresAction and
Processing. Both keep the old Pending behaviour: reconcile answers
`pending` and reschedules without consuming an attempt, release reopens
the session with its intent intact, and the processing page keeps
polling.
…ayload

PaymentIntentDescriptor dropped `clientSecret` for an opaque
`clientPayload`. The payment-intent response keeps its `clientSecret`
key, which the Stripe components and the host apps read, and fills it
from `clientPayload['client_secret']`.

Two test gateways passed the secret as the second positional argument,
which now binds to `redirectUrl`. They use the named argument, and a
test asserts the response carries the payload's secret.
Core removed describeHold() and HoldDescription. The confirm page now
verifies a hold with fetchIntent() and reads the authorised amount and
wallet label from the snapshot. adjustHold() and captureHold() take the
Cart and a PriceValue in the cart's currency.

NeedsReauthorization still rejects the pay attempt with
`hold_reauthorization_required` while the session stays Open.
…registry

Core alpha.9 builds the order-create validation list from the Steps
registry and throws RemovedStepConfigException as soon as any list is read
while lunar.cart.validators exists. The provider wrote that key, so every
cart calculation in an app using this package would have failed.

The provider now appends PickupPointRequired to StepList::OrderCreateValidation
in boot(). append() skips a step that is already listed, so a second boot
registers it once. It stays in boot() because core binds the StepManifest in
its own register(): registering here fails to resolve the manifest when the
checkout provider is listed ahead of core, which a new test covers.

Tests that injected closures through lunar.orders.pipelines.creation now
prepend a small throwing step class, since the registry only takes class
strings. The bare-validators test case modelled a host config that can no
longer exist, so the test asserts the resolved list and the absence of the
legacy key instead.
…name

Core alpha.9 renamed ShippingOption::$collect to $pickup (and the order
shipping line meta key collect to pickup). The package read the old
property in its shipping modifier, fulfilment action, pickup point support
and checkout driver, so a collect option was no longer recognised.

Only core API names change. The package's own checkout mode string
'collect', its JSON projection key, routes, config and customer copy are
untouched. Tests build options with pickup: and assert meta['pickup'] and
the pickup property.
Core alpha.9 caches cart totals: calculate() may serve a persisted
snapshot up to lunar.cart.totals.ttl old, or the in-process memo, so a
price changed outside the cart's revision went unseen at the pay
boundary. Intent and hold creation, the session snapshot and
fingerprint, the pay pin and completion's verify now recalculate.

The checkout page reuses its snapshot's fingerprint instead of
calculating the cart a second time.
The webhook listener pins amount_total and the fingerprint from one
CheckoutDriver::snapshot(). The test pinned the amount from a plain
calculate() instead, which in a single test process can return the
memoised totals core restores onto a re-queried cart, so it no longer
modelled the listener. The assertions are unchanged and still fail
against the stale-totals driver.
Core alpha.9 caches each line's calculated properties, so calculate() on
a re-queried cart returns the in-request memo (or hydrates the persisted
snapshot) without the pipeline's eager loads. Shipping modifiers and the
line projection then lazy-load each line's purchasable, which a host
running Model::preventLazyLoading() rejects with a 500.

resolveCart() loads lines.purchasable, and getLines() loads the variant
product, thumbnail and images it projects.
Core alpha.9 mails the customer when an order is placed
(SendOrderPlacedNotifications). With the log mailer, a test that spies
on the Log facade hands the log transport a null logger and the
placement throws. No test reads mail from the log.
Core alpha.9 resolves the storefront context, default language
included, when it calculates a cart. A session created on an empty cart
before any language existed memoised a null default for the request,
and the product factory's URL generator then failed on it. A real
store always has a default language, so the fixture creates one.
…er too long

Stripe on alpha.9 reports requires_payment_method, requires_confirmation
and requires_action as PaymentIntentStatus::RequiresAction, and a declined
confirmation drops back to requires_payment_method. The monorepo driver
reported a decline as Failed, which reopened the session. Reconciliation
treated RequiresAction as pending with no attempt counted, so a decline
followed by a closed tab, a failed redirect return or an async failure
left the session in PaymentProcessing for good: the cart stayed locked,
a restart got 409 sibling_payment_processing, the expiry sweep skipped
it and nothing ever stalled to alert an operator.

RequiresAction is now pending only for
lunar.checkout.reconciliation.requires_action_minutes (default 30) after
the pin. Past that the session returns to Open with the intent kept,
through the helper release() and a failed hold capture already use, with
no attempt counted and no event. The outcome code is
intent_requires_action, formed like intent_failed and intent_voided. A
pin with no timestamp counts as past the window, because it could never
age into it. Processing stays pending without a bound, since it settles
on its own.

The customer can still finish the payment afterwards: the webhook
listener adopts the Open session, and a hold-mode session routes to the
confirm page once its hold is authorised. If they never return, the
expiry sweep voids the intent.
…ency

pinnedAmount() paired the session's amount_total with the cart's current
currency. amount_total is in the session's currency_code, and the cart
can change currency after the pin. Stripe refuses a PriceValue whose
currency differs from the intent's, so a refund or a hold capture that
worked on the monorepo driver now threw: a refund-failed stall, or a
spurious hold-capture-failed.

The amount is now built from the Currency whose code is the session's
currency_code. This covers the hold capture, the refund after a failed
completion and the operator's forced refund. The controller's adjustHold
call is left alone: it sends the live amount in the live currency.

If the store no longer has that currency, pinnedAmount() throws
PaymentIntentException instead of falling back to the cart's currency,
which by then is known to be the wrong one. Stripe's own intentCurrency()
does the same. The existing handlers take it from there: the capture
reopens with the hold kept, the refund counts an attempt towards a stall,
and the operator command shows the message.

The test gateways now record the currency of each refund.
The alpha.9 intent verbs take the cart, so reconcile, release and
void-first invalidation loaded it with Cart::query()->find(). Lunar's
Cart soft-deletes and lunar:prune:carts soft-deletes idle carts, so once
a cart was pruned those loads returned null. The operator's
--resolve=refund answered refund-failed without calling the gateway, the
sweep counted attempts until it stalled, and an expired session holding
an intent could never be voided. The monorepo driver worked by reference
alone and had none of these gaps.

PaymentIntentGateway::cartFor() now resolves the cart with trashed rows
included, and the three sites use it:

- ReconcileCheckoutSession::execute(), which covers the sweep, the
  customer's poll and the operator override.
- ReconcileCheckoutSession::release(), so it answers from the same
  facts as execute() instead of unconfirmed.
- InvalidateCheckoutSession::execute(), so the expiry sweep can void the
  intent and cancel the session.

The controller's liveHold() keeps the plain lookup. It decides whether
to render the confirm page for a customer about to capture, and
completion refuses a deleted cart, so "no live hold" is the right answer
there. The expiry sweep then voids that hold.

A captured payment on a pruned cart cannot complete, so the sweep now
refunds it instead of stalling.
The specs still described the monorepo build. No behaviour changes here.

- Pickup: core's flag, order line meta, shipping driver, fulfilment
  method and states are pickup, Pickup, "Ready for pickup" and "Picked
  up", and the panel exposes pickup. The package's own collect mode and
  customer copy keep their names.
- Steps: PickupPointRequired is appended in boot() through
  Steps::for(StepList::OrderCreateValidation), and address writes run
  the StepList::AddAddressValidation steps. The lunar.cart.validators
  config keys no longer exist.
- Payment intents: SupportsPaymentIntents is ReconcilesPaymentIntents.
  Its verbs and the hold verbs take the cart first, amounts are
  PriceValue, fetchIntent() returns a nullable PaymentIntentSnapshot
  and refundIntent() returns a PaymentRefund. PaymentIntentStatus has
  RequiresAction and Processing in place of Pending.
PickupPointValidationTest repeated, word for word, the assertion
OrderCreateValidatorsTest already makes about the order of the
order-create validation steps.
…ng options

SetFulfilment receives a refreshed cart from the driver's address and
option verbs. calculate() then serves the persisted totals snapshot, which
skips the pipeline's eager load, and resolving the shipping options reads
every line's purchasable. On a multi-line cart under preventLazyLoading
that was a LazyLoadingViolationException when the customer picked the
collect option or saved an address in collect mode.
…intent creation

pay() and storePaymentIntent() resolved the method, its availability and
any payment guard against an unforced calculate(), which can serve the
persisted totals snapshot, and only then pinned or created the intent on
recalculated totals. A minimum amount or a credit limit could therefore
pass on a stale figure. Both actions now load the cart once, recalculate
it, and hand that same instance to every decision and gateway call, so
the forced recalculations per request stay the same.
…esh totals

The controller-level fresh totals tests stayed green with the pay gate's
locked recalculation reverted to calculate(), and never reached
complete(). These drive the driver directly: reprice behind persisted
totals that calculate() would still serve, then expect the pin and the
completion verify both to refuse with fingerprint_mismatch.
…teway success listener

The listener locked the session row and then took the cart snapshot,
which now writes the cart row's totals cache. The pay boundary locks the
cart row and then writes the session row, so a gateway success for an
Open session racing that session's pay could deadlock. The snapshot now
runs before the session lock. The lock never guarded the cart: a cart
change after the snapshot fails complete()'s verify under the cart-row
lock, and a session moved meanwhile fails the locked Open check.
Every other store verb returns a snapshot built from forced totals.
associateCustomer() built its snapshot from an unforced calculate(), so a
host reading it could get the persisted totals and a fingerprint the pay
boundary would reject.
The contract said reads never write. Since alpha.9 a snapshot
recalculates the cart, and core persists those totals to the cart row.
…ore documents

Core's CreatesPaymentIntents contract on alpha.9 says a driver's
authorize() receives the intent as withData(['reference' => ...]).
recordPayment() only sent payment_intent, which Stripe still reads as a
fallback but another driver written to the contract would not find.

It now sends both keys with the same value, so a driver written to
either one records the payment.
Stripe on alpha.9 throws PaymentIntentException from adjustHold() and
syncIntent() for an intent in another currency, one not created for the
cart, or a hold no longer awaiting capture. pay() let it through as a
500, and for a cart that changed currency it did so before the gate's
step 0 could void the intent and cancel the session.

pay() now skips the resize when the cart has left the session's
currency, so the gate cancels the session as context_diverged. A refused
adjustHold() is reported and answered with the existing
hold_reauthorization_required 422, which the confirm page already
handles by renewing the hold. A refused syncIntent() is reported and
answered with the same payment_method message a failed intent creation
uses. The session stays Open in both cases.

The currency-change test fixture now re-prices its shipping option in
the new currency, so a cart in that currency can be calculated.
…iled redirect

A redirect payment method (Klarna, PayPal, a full-page 3DS challenge)
that fails or is cancelled sends the customer back to the session page,
which StripeCard.vue gives Stripe as its return_url. The session was
still pinned, because the in-page release only runs when the
confirmation fails without leaving the page. On alpha.9 Stripe reports
the declined intent as RequiresAction, which reconciliation treats as
pending, so the customer faced a frozen checkout for up to 30 minutes.
On main the old driver reported Failed and the page reopened at once.

show() now runs the customer-initiated release when the request carries
redirect_status=failed and a payment_intent equal to the session's own
reference. The release asks the gateway first: a captured intent
completes or refunds, and only an uncaptured one reopens, with the
intent kept. A reopened session redirects to the page with
?payment=failed, which shows the retry message and drops Stripe's
parameters from the URL.

The fix is server-side so that consumers do not need a rebuilt dist/.
The two parameter names are the only gateway knowledge the controller
gains, and the session's owner can already ask for the same release
through the payment-release route.
…fore reopening

db64e4c reopened a session whose intent had waited on the customer past
the window and kept the intent. The intent stayed confirmable, so a
payment that went through after the reopen had nothing to settle it when
webhooks were down: the sweep skips Open sessions, the processing page
showed a failure, and a retry minted a second intent, which left an
orphaned or double charge.

The timed path now voids the intent first and then reopens with the
reference cleared, so the retry starts on a fresh intent. If the gateway
refuses the void, because the payment went through between the fetch and
the void, the session stays pinned and the pass counts an attempt. The
next pass reads the real status and completes, and a void that keeps
failing stalls with the operator alert. The outcome code is still
intent_requires_action and no CheckoutCompletionFailed event fires.

The customer-initiated release still keeps the intent, because the
customer is on the page with the payment element bound to it. A
hold-mode session follows the same timed rule: a hold that never got
authorised is voided, and the customer opens the wallet again.
A Stripe intent stays succeeded after a refund, so reconciliation still
read it as Captured. Two failures followed from ignoring the snapshot's
refunded amount.

If a pass refunded and then died before its reopen committed, the
session stayed pinned, and the next pass completed it and placed an
order on refunded money. If the refund landed but its response was lost,
every later pass asked for the refund again, alpha.9 Stripe refused
because nothing was left to refund, and the session stalled while firing
refund-failed on each attempt.

execute() and release() now keep the intent snapshot and check its
refunded amount before they capture or complete. A fully refunded intent
reopens the session under the same lock and guards as a normal refund,
without a second refund call, and fires CheckoutCompletionFailed with
reason refunded. The refund reference is null there: the snapshot
carries amounts only, and the call that made the refund never returned
one. A partly refunded intent records an attempt and stalls to the
operator, because part of the money is still held with no order.
…ccess pinned the session

The placed-order guard in moneyBack() counted an order as placed for
this payment only when placed_at was at or after the pin. A session that
CompleteSessionOnPaymentSuccess pins is pinned after Stripe's authorize()
stamped placed_at, so the guard missed the order unless both fell in the
same second. If complete() then threw, the webhook retry returned early
without firing the event again, reconciliation read the intent as
Captured, complete() failed again, and the refund went out against a
placed order.

The listener now notes on the session which order the gateway announced
and for which intent, before it pins or completes, on every path. The
guard treats that order as placed for this payment when the noted intent
is the one being reconciled. The intent keeps the scope 3965316 chose: a
note left by an earlier payment on the same session does not block the
refund of a later one. The time comparison stays as the second signal,
for a placement whose announcement never reached the listener.
…noting the gateway's order

52f610d refreshed the session after it noted the gateway's order. If
another process ended the session between the listener's read and that
note, the refreshed copy no longer read Open, so the listener skipped
the pin and called complete() on a cancelled session. complete() fired
OrderPlacing and then threw CheckoutSessionConflictException. Before
52f610d the pin's locked re-read caught that case and the listener
returned.

The note no longer refreshes the caller's copy, so the listener decides
on the status it read and the pin's re-read catches the change again.
…ocumented Stripe parameter

Stripe's return_url documentation lists payment_intent and
payment_intent_client_secret. It does not list redirect_status, which
Stripe appends all the same and which show() reads to release a session
after a failed redirect. The controller docblock and spec 0010 section F
now say so, and say that a return without the parameter only costs the
wait for reconciliation.
@alecritson
alecritson marked this pull request as ready for review November 12, 2026 10:22
@alecritson
alecritson merged commit ff72738 into main Nov 12, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant