Session Creation
Create checkout sessions from the browser with @flopay/js.
Session Creation
@flopay/js exports createCheckoutSession and createCheckoutSessionWithRetries for creating checkout sessions directly from the browser. These functions post to the billing API and redirect the user to the hosted checkout page.
createCheckoutSession
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
billingApiUrl | string | -- | Billing API base URL (required) |
checkoutBaseUrl | string | -- | Hosted checkout page base URL (required) |
clientId | string | -- | Client identifier (required) |
items | Array | [] | One-time purchase items |
subscriptions | Array | [] | Recurring subscription plans |
account | object | -- | Customer account data (required) |
successUrl | string | -- | URL to redirect on success (required) |
cancelUrl | string | -- | URL to redirect on cancel (required) |
checkoutMode | string | 'confirm' | Checkout mode |
couponCodes | string[] | [] | Coupon codes to apply |
tagsData | object | -- | Optional tags metadata |
redirectParams | Record<string, string> | {} | Extra query params for the checkout redirect URL |
setCookie | boolean | true | Set a checkout_data cookie with the cancel URL |
timeoutMs | number | 12000 | Request timeout in milliseconds |
utmMetadata | Array | -- | UTM tracking metadata |
Item Shape
Account Shape
Response Behavior
| Status | Behavior |
|---|---|
201 | Session created -- redirects to {checkoutBaseUrl}/secure?id={uuid}&...redirectParams |
204 | Payment method already on file -- redirects to successUrl |
| Other | Returns { status } without redirecting |
Retry with Backoff
createCheckoutSessionWithRetries wraps createCheckoutSession with automatic retry on timeout/abort errors using exponential backoff (100ms, 200ms, 400ms, etc.):
Only AbortError (timeout) triggers a retry. Other errors are thrown immediately. The maxRetries parameter must be a positive integer.
For server-side session creation, prefer @flopay/node which uses flopay.checkout.sessions.create(). The browser-side createCheckoutSession is designed for client-side redirects where you want the user's browser to navigate to the hosted checkout page.