Cart Payment Endpoints

core/services/cart_service.dart (payment + complete)

data

Overview

Subset of CartService used by checkout: payment-providers, payment-collection, full / partial payment-session, completeCart. The booking-deposit path uses createPartialPaymentSession to split between Stripe and pay-on-site.

User Flow

fetchPaymentProviders(regionId) → GET /store/payment-providers.
createPaymentCollection(cartId) → POST /store/payment-collections.
updatePaymentCollectionAmount(id, amount) → resync when discounts change.
createPaymentSession(collectionId, providerId) → full-amount session, returns payment_sessions[].data.client_secret.
createPartialPaymentSession(collectionId, deposit, rest) → splits providers (pp_partial_stripe-connect, pp_system_default).
completeCart(cartId) → POST /store/carts/{id}/set-order; returns the order_set wrapping the resulting orders.

Cases & Edge Cases

completeCart accepts three response shapes (order_set / data / {type:'order'}) — Medusa versioning, do not reduce.
createPartialPaymentSession amounts are double-truncated to 2dp before send to avoid Stripe rejecting a floating-point mismatch.
Provider IDs are stringly typed — magic strings 'pp_system_default' and 'pp_partial_stripe-connect' must match backend config exactly.

Code References

lib/src/core/services/cart_service.dart:463 // fetchPaymentProviders
lib/src/core/services/cart_service.dart:500 // createPaymentCollection
lib/src/core/services/cart_service.dart:570 // createPaymentSession
lib/src/core/services/cart_service.dart:612 // createPartialPaymentSession
lib/src/core/services/cart_service.dart:663 // completeCart

API Calls

GET/store/payment-providers?region_id=:idno status
Resolve the payment providers wired for the cart's region.
Response
```
{ payment_providers: [{ id: string, ... }] }
```
lib/src/features/shared/checkout/views/widgets/checkout_payment_methods.dart
auth: customer.
POST/store/payment-collectionsno status
Open a payment collection for the cart.
Request
```
{ cart_id: string }
```
Response
```
{ payment_collection: { id: string, amount: number, payment_sessions: [] } }
```
lib/src/features/shared/checkout/views/checkout_screen.dart
auth: customer.
POST/store/payment-collections/:idno status
Resync the collection amount after cart mutation.
Request
```
{ amount: number }
```
Response
```
{ payment_collection: PaymentCollection }
```
lib/src/features/shared/checkout/views/checkout_screen.dart // amount resync
auth: customer.
POST/store/payment-collections/:id/payment-sessionsno status
Initialize a payment session for a single provider; returns the Stripe client_secret.
Request
```
{ provider_id: string }
```
Response
```
{ payment_collection: { payment_sessions: [{ provider_id, data: { client_secret } }] } }
```
lib/src/features/shared/checkout/views/checkout_screen.dart
auth: customer.
POST/store/payment-collections/:id/partial/payment-sessionno status
Initialize multi-provider partial payments for a booking deposit (deposit + remainder).
Request
```
{ providers: [{ provider_id: 'pp_partial_stripe-connect' | 'pp_system_default', amount: number }] }
```
Response
```
{ payment_collection: PaymentCollection }
```
lib/src/features/shared/checkout/views/checkout_screen.dart // booking deposit
auth: customer.
POST/store/carts/:cartId/set-orderno status
Finalize the cart and convert it into a paid order.
Response
```
{ order_set?: OrderSet, data?: any, order?: Order } /* shape varies */
```
lib/src/features/shared/checkout/views/checkout_screen.dart // Pay → completeCart
auth: customer.

Notes

These endpoints live in CartService — see the cart feature for the broader API surface; this node names the slice that checkout owns.