Configuration

Every Checkout Components integration follows the same three-step sequence: initialize the SDK, mount your components, then load a session. This page is the API reference for the methods that handle each step — FastSpring.init(), sdk.components.create(), and sdk.checkout() — including all options, parameters, and return values.

For component-specific options and style properties, see Card, Pay Button, and Disclosures.

`FastSpring.init(options)`

Initializes the SDK — call once after the script loads

Returns an sdk instance used for all subsequent calls: mounting components, loading sessions, and registering lifecycle callbacks.

const sdk = FastSpring.init({
    checkoutUrl: 'https://<your-store>.onfastspring.com/<your-checkout>',
});

Options

Option	Type	Required	Default	Description
`checkoutUrl`	`string`	✅	—	URL of your Component Checkout. Found in the FastSpring app under Checkouts → Component Checkouts → [your checkout] → Implementation. Must point to a component checkout — popup and embedded checkout URLs are not supported.
`debug`	`boolean`		`false`	When `true`, shows built-in success and failure dialogs during testing. Disable before going to production.
`globalStyles`	`object`		—	Base styles applied across all mounted components. Accepts `color`, `fontFamily`, and `fontSize`. Component-level styles always take precedence. See Style API.

Callbacks

Register lifecycle callbacks here. They remain active for the lifetime of the sdk instance. For parameter shapes and firing order, see the Callbacks reference.

Callback	When it fires
`onSessionLoaded`	Session data fetched — checkout is ready for input
`onOrderCompleted`	Payment succeeded and order is complete
`onPaymentFailed`	Payment attempt rejected or errored

`sdk.checkout(sessionId, callbacks)`

Loads a session into the mounted components — call once per checkout attempt

Fetches the session data and activates the Card and Pay Button. Must be called after components are mounted and with a freshly created session ID.

sdk.checkout('<SESSION_ID>', {
    onSuccess: () => {
        console.log('Checkout is ready.');
    },
    onError: (error) => {
        console.error('Session load failed:', error);
    },
});

Parameters

Parameter	Type	Required	Description
`sessionId`	`string`	✅	The session ID returned by the FastSpring Sessions API. Create the session server-side immediately before calling `sdk.checkout()`.
`onSuccess`	`function`		Fired when the session loads successfully and the checkout is ready for input.
`onError`	`function`		Fired when the session fails to load. Receives an error object.

💡
Create a fresh session immediately before each sdk.checkout() call. Sessions are single-use and expire — reusing or pre-creating them is the most common cause of onError firing with a 404 or session-not-found response.

`sdk.components.create(type, options)`

Creates a component instance — call once per component

Returns a component object. Call .mount(selector) on it to attach the component to a DOM element. Must be called after FastSpring.init() and before sdk.checkout().

sdk.components.create('fs-card', { /* options */ }).mount('#card-element');

Parameters

Parameter	Type	Required	Description
`type`	`string`	✅	Component type. One of `'fs-card'`, `'fs-pay-button'`, `'fs-disclosures'`.
`options`	`object`		Component-specific options and `style` object.

For component-specific options and style properties, see:

Card — labelMode, hideCardHeader, and all card style categories
Pay Button — button, text, spinner, and disclosure style categories
Disclosures — container and link style categories