FloPay
Guides

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

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

ParameterTypeDefaultDescription
billingApiUrlstring--Billing API base URL (required)
checkoutBaseUrlstring--Hosted checkout page base URL (required)
clientIdstring--Client identifier (required)
itemsArray[]One-time purchase items
subscriptionsArray[]Recurring subscription plans
accountobject--Customer account data (required)
successUrlstring--URL to redirect on success (required)
cancelUrlstring--URL to redirect on cancel (required)
checkoutModestring'confirm'Checkout mode
couponCodesstring[][]Coupon codes to apply
tagsDataobject--Optional tags metadata
redirectParamsRecord<string, string>{}Extra query params for the checkout redirect URL
setCookiebooleantrueSet a checkout_data cookie with the cancel URL
timeoutMsnumber12000Request timeout in milliseconds
utmMetadataArray--UTM tracking metadata

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

StatusBehavior
201Session created -- redirects to {checkoutBaseUrl}/secure?id={uuid}&...redirectParams
204Payment method already on file -- redirects to successUrl
OtherReturns { 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.

On this page