FloPaycreateCheckoutSession
Functions for creating checkout sessions via the billing API and redirecting users.
createCheckoutSession
Creates a checkout session via the billing API and redirects the user to the hosted checkout page.
async function createCheckoutSession(
options: CreateSessionParams
): Promise<CheckoutSessionResult>Behavior
- 201: Redirects to
{checkoutBaseUrl}/secure?id={uuid}&...redirectParams}. Returns{ status: 201, redirectUrl: string }. - 204: Redirects directly to
successUrl(payment method already on file). Returns{ status: 204 }. - Other: Returns
{ status: number }without redirecting.
When setCookie is true (default), a checkout_data cookie is set with the cancelUrl for navigation purposes.
Session-level currency is required. The SDK throws FloPayError({ type: 'validation_error', code: 'CurrencyRequired' }) synchronously — before any network call — when no currency can be resolved from the session-level field or any per-line currency on items / subscriptions / products.
Parameters
See CreateSessionParams for the full parameter table.
Example
Pass products[] — each entry is a catalog entry identified by code. The backend resolves the name, price, and whether it bills as a one-off purchase or a recurring subscription from the catalog.
import { createCheckoutSession } from '@flopay/js';
const result = await createCheckoutSession({
billingApiUrl: 'https://billing.example.com',
checkoutBaseUrl: 'https://checkout.example.com',
clientId: 'client_123',
currency: 'USD',
products: [
{ code: 'starter', totalAmount: 24.95 },
{ code: 'pro_monthly', totalAmount: 9.99 },
],
account: {
userId: 'user_1',
email: 'user@example.com',
},
successUrl: '/success',
cancelUrl: '/cancel',
redirectParams: {
email: 'user@example.com',
bg: 'courses',
mode: 'confirm',
},
});The SDK also accepts the legacy items / subscriptions shape and folds it into products[] internally, so existing integrations keep working — set currency and prefer products[] for new code.
createCheckoutSessionWithRetries
Creates a checkout session with automatic retry on timeout/abort errors. Uses exponential backoff: 100ms, 200ms, 400ms, etc.
async function createCheckoutSessionWithRetries(
options: CreateSessionParams & { maxRetries?: number }
): Promise<CheckoutSessionResult>Parameters
Accepts all CreateSessionParams plus:
| Parameter | Type | Required | Description |
|---|---|---|---|
maxRetries | number | No | Maximum number of retry attempts. Defaults to 3. Must be a positive integer. |
Retry Behavior
- Only retries on
AbortError(i.e. timeout). - Non-abort errors are thrown immediately.
- Backoff delay:
100ms * 2^attempt(100ms, 200ms, 400ms).
Example
import { createCheckoutSessionWithRetries } from '@flopay/js';
const result = await createCheckoutSessionWithRetries({
billingApiUrl: 'https://billing.example.com',
checkoutBaseUrl: 'https://checkout.example.com',
clientId: 'client_123',
currency: 'USD',
products: [{ code: 'pro_plan', totalAmount: 49.99 }],
account: { userId: 'user_1', email: 'user@example.com' },
successUrl: '/success',
cancelUrl: '/cancel',
maxRetries: 5,
timeoutMs: 8000,
});