@spree/docs 0.1.289 → 0.1.290

package/dist/developer/core-concepts/payments.md

@@ -239,7 +239,9 @@ sequenceDiagram
 
 The frontend calls the API to create a Payment Session for a specific payment method and order. Spree calls the gateway to create a provider-side session (e.g., Stripe PaymentIntent, Adyen Session) and returns the session data including a `client_secret` for the frontend SDK.
 
-    > **INFO:** The payment session should be created (or recreated) **after** the shipping method is selected, so the amount includes shipping costs. If the order total changes (e.g., customer selects a different shipping rate or applies a coupon), create a new payment session with the updated amount.
+    > **INFO:** Create the payment session **after** the shipping method is selected, so the amount includes shipping costs. If the order total changes (a different shipping rate, a coupon), create the session again.
+
+    A cart has at most one open session per gateway. Asking Stripe for a session again (a reloaded checkout page, a second tab) cancels the cart's open session and opens a new one, because every open Stripe PaymentIntent can be paid on its own. If that session has already been paid, the request fails with a `gateway_error` and the paid session stays open. Once the order is placed, a background job cancels any session still pending — for example, one left behind when the customer switched to a different payment method — so it can no longer be paid.
 
   **Step 2: Customer pays on the frontend**
 
@@ -373,8 +375,9 @@ stateDiagram-v2
 ```
 
 > **NOTE:** There is no cancel endpoint. A session reaches `canceled` when the provider
->   says so through its webhook, and `expired` when it passes `expires_at`.
->   Neither is something a storefront drives.
+>   says so through its webhook, or after the order is placed while the session
+>   is still pending with nothing paid through it. It reaches `expired` when it
+>   passes `expires_at`. Neither is something a storefront drives.
 
 #### API
 

package/dist/developer/how-to/custom-payment-method.md

@@ -158,12 +158,22 @@ class MyGateway < Spree::PaymentMethod
     payment_session
   end
 
+  # Cancel a session the customer left behind, so it can no longer be paid.
+  # Spree calls this from a background job, once the order is placed, for
+  # every session still pending with nothing paid through it.
+  def cancel_payment_session(payment_session:)
+    MyProvider::Client.new(preferred_api_key).cancel_session(payment_session.external_id)
+    payment_session.cancel
+  end
+
   def payment_icon_name
     'my-gateway'
   end
 end
 ```
 
+> **WARNING:** If your provider lets each open session be paid on its own (as Stripe does with PaymentIntents), a customer with two open sessions can be charged twice — for example, with checkout open in two tabs. Have `create_payment_session` cancel the cart's open sessions for your gateway before opening a new one, and implement `cancel_payment_session`. Leave a session the provider has already accepted, and do not open another. The built-in Stripe gateway does both. If you leave out `cancel_payment_session`, sessions still pending when the order is placed stay open at your provider.
+
 ### How the Frontend Uses It
 
 The frontend creates a session, then uses the provider's SDK to collect payment:
@@ -194,7 +204,7 @@ const completed = await client.carts.paymentSessions.complete(
 const order = await client.carts.complete(cart.id, options)
 ```
 
-> **INFO:** **Important:** Always create the payment session **after** shipping is selected. If the order total changes (shipping rate change, coupon applied), create a new payment session with the updated amount. The `complete` call in step 5 only handles payment — step 6 finalizes the order.
+> **INFO:** **Important:** Always create the payment session **after** shipping is selected. If the order total changes (shipping rate change, coupon applied), update the session with the new amount (`client.carts.paymentSessions.update`) rather than creating another one. The `complete` call in step 5 only handles payment — step 6 finalizes the order.
 
 ## Step 4: Handle Webhooks (Recommended)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.289",
+  "version": "0.1.290",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",