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

import { createCheckoutSession } from '@flopay/js';
 
await createCheckoutSession({
  billingApiUrl: 'https://billing.example.com',
  checkoutBaseUrl: 'https://checkout.example.com',
  clientId: 'client_123',
  items: [
    {
      providerItemId: 'prod_abc',
      providerItemName: 'Pro Plan',
      totalAmount: 49.99,
      overrideAmount: 24.99,
      currency: 'USD',
    },
  ],
  account: {
    userId: 'user_1',
    email: 'user@example.com',
    firstName: 'Jane',
    lastName: 'Doe',
    country: 'US',
  },
  successUrl: '/success',
  cancelUrl: '/cancel',
  redirectParams: {
    email: 'user@example.com',
    bg: 'courses',
    mode: 'confirm',
  },
});

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
`avsCheck`	`boolean`	--	Whether AVS will be enabled for this session. See Checkout Analytics
`avsConfig`	`AVSFieldConfig`	--	Resolved per-field AVS exposure (booleans only — resolved against the buyer's country, not the raw rules)
`checkoutType`	`'standard_checkout' \| 'embedded_checkout'`	--	Checkout surface
`checkoutLayout`	`'default_layout' \| 'buttons_layout' \| 'custom_layout'`	--	Checkout layout

Item Shape

{
  providerItemId: string;     // Product ID in the provider (e.g., Stripe price ID)
  providerItemName?: string;  // Display name
  quantity?: number;           // Default: 1
  totalAmount: number;         // Price in dollars
  overrideAmount?: number;     // Discounted price (if different)
  currency?: string;           // Default: 'USD'
}

Account Shape

{
  userId: string;        // Required
  email: string;         // Required
  firstName?: string;
  lastName?: string;
  country?: string;
  gender?: string;
  city?: string;
  state?: string;
  zip?: string;
}

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.):

import { createCheckoutSessionWithRetries } from '@flopay/js';
 
const result = await createCheckoutSessionWithRetries({
  billingApiUrl: 'https://billing.example.com',
  checkoutBaseUrl: 'https://checkout.example.com',
  clientId: 'client_123',
  items: [{ providerItemId: 'prod_abc', totalAmount: 49.99 }],
  account: { userId: 'user_1', email: 'user@example.com' },
  successUrl: '/success',
  cancelUrl: '/cancel',
  maxRetries: 3, // default
});

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.

Analytics Fields

avsCheck, avsConfig, checkoutType, and checkoutLayout describe how the checkout will be presented to the buyer. The SDK populates them automatically when you use FloPayCheckout. If you create sessions server-to-server (without the SDK), you can pass them in the create body to populate analytics on every session — including abandoned ones — or omit them to let the SDK fill them in at process time.

See the Checkout Analytics guide for the full schema, write semantics (atomic, race-safe, first-writer-wins), and example queries.

Session Creation

On this page