Document Storefront customer auth and Stripe capture contracts

collections/apis/storefront-api/README.md

@@ -13,6 +13,12 @@ Reference collection for Fleetbase Storefront API requests.
 
 Requests inherit bearer token authentication from the collection. Set `api_key` locally or through Postman Vault.
 
+The bearer token identifies the storefront. Customer-scoped requests additionally send the customer session token as `Customer-Token`. Profile update requests require that token and reject attempts to update a different customer.
+
+## Checkout capture
+
+`Capture checkout as order` is idempotent and verifies Stripe payments on the server. Confirm the PaymentIntent returned by checkout initialization before capture; Fleetbase uses the PaymentIntent linked to the checkout and rejects incomplete, missing, or mismatched payments. A concurrent capture can return `409` while the first request is still in progress and can be retried with the same checkout token.
+
 ## Coverage
 
 The editable Postman Local Mode collection lives at `postman/collections/Fleetbase Storefront API`. It uses `api_prefix=storefront`, so versioned request URLs resolve as `{{base_url}}/{{api_prefix}}/{{namespace}}/...`.

postman/collections/Fleetbase Storefront API/Checkout/Capture checkout as order.request.yaml

@@ -1,6 +1,10 @@
 $kind: http-request
 description: |-
-  Captures a checkout token and creates the corresponding order. The response returns the completed order or the existing order when the checkout was already captured. Gateway checkouts must be paid before capture — a Stripe checkout whose PaymentIntent has not succeeded is refused with `402` — so this example captures the cash pickup checkout, which needs no provider payment.
+  Captures a checkout token and creates the corresponding order. Capture is idempotent: an already completed checkout returns its existing order, while a concurrent capture still in progress returns `409` so the client can retry safely.
+
+  Stripe checkouts are captured only after Fleetbase retrieves the server-linked PaymentIntent and verifies that it succeeded and matches the checkout amount, currency, customer, and live/test mode. An incomplete payment returns `402`, a missing or mismatched PaymentIntent returns `422`, and a temporary Stripe verification failure returns `502`. Clients must confirm the PaymentIntent before calling this endpoint and must not send or trust a client-selected PaymentIntent ID during capture.
+
+  Because a contract run cannot complete a card payment, this example captures the cash pickup checkout created by `Before Cash Pickup Checkout`, which needs no provider payment; the unpaid Stripe checkout's `402` refusal is asserted by `Capture Stripe checkout without payment`.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/checkouts/capture"
 method: POST
 headers:

postman/collections/Fleetbase Storefront API/Customer/Update Contact Customer Alias.request.yaml

@@ -1,6 +1,6 @@
 $kind: http-request
 description: |-
-  Updates a storefront customer through the legacy contact alias route. The request is handled by the same customer update controller as `/customers/{id}` and carries the same authorization contract: it must be authenticated with the `Customer-Token` of the customer being updated.
+  Updates the authenticated storefront customer through the legacy contact alias route. The request is handled by the same customer update controller as `/customers/{id}` and carries the same authorization contract: the `Customer-Token` must belong to the customer addressed by `customer_id`, and missing or mismatched customer credentials return `403 Not authorized to update customer.`
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/contacts/{{customer_id}}"
 method: PUT
 headers:

postman/collections/Fleetbase Storefront API/Customer/Update a Customer.request.yaml

@@ -1,6 +1,6 @@
 $kind: http-request
 description: |-
-  Updates a storefront customer profile. The request must be authenticated as the customer being updated: the `Customer-Token` identity is authoritative and a token belonging to a different customer is rejected with `403`. The response returns the customer with the new values applied.
+  Updates the authenticated storefront customer's profile. The `Customer-Token` identity is authoritative and must belong to the customer addressed by `customer_id`; missing or mismatched customer credentials return `403 Not authorized to update customer.` The response returns the customer with the new values applied.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/customers/{{customer_id}}"
 method: PUT
 headers: