@fastspring/checkout-sdk

Embed FastSpring's payment components directly into your page — card form, pay button, and disclosures — with full control over styling and layout.

Installation

npm install @fastspring/checkout-sdk

Or include directly via CDN:

<script src="https://cdn.onfastspring.com/checkout-sdk/latest/fastspring-sdk.js"></script>

Quick start

import { FastSpring } from '@fastspring/checkout-sdk';

// 1. Initialize
const sdk = FastSpring.init({
  checkoutUrl: 'https://<your-store>.onfastspring.com/<your-checkout>',
  onOrderCompleted: (data) => console.log('Order completed!', data),
  onPaymentFailed:  (error) => console.error('Payment failed:', error),
});

// 2. Mount components
sdk.components.create('fs-card', {}).mount('#card-element');
sdk.components.create('fs-pay-button', {}).mount('#pay-button-element');
sdk.components.create('fs-disclosures', {}).mount('#disclosures-container');

// 3. Load a session (create server-side via the Sessions API)
sdk.checkout('<SESSION_ID>', {
  onSuccess: () => console.log('Checkout ready'),
  onError:   (err) => console.error('Session load failed:', err),
});

<div id="card-element"></div>
<div id="pay-button-element"></div>
<div id="disclosures-container"></div>

Prerequisites

• A FastSpring account with a Component Checkout configured.
• Your checkout URL — found in the FastSpring app under Checkouts → Component Checkouts → [your checkout] → Implementation.
• A server endpoint that creates sessions via the FastSpring Sessions API and returns a session ID.
• Your domain added to the checkout's allow list (see Set up Component Checkouts).

API

FastSpring.init(options)

Initializes the SDK and returns an sdk instance.

| Option | Type | Required | Description | | :----- | :--- | :------- | :---------- | | checkoutUrl | string | ✅ | URL of your Component Checkout. | | debug | boolean | | Show built-in success/failure dialogs during testing. Default: false. | | globalStyles | object | | Base styles applied to all components (color, fontFamily, fontSize). | | onSessionLoaded | function | | Fired when session data is fetched and the checkout is ready. | | onOrderCompleted | function | | Fired after a successful payment. Receives order confirmation data. | | onPaymentFailed | function | | Fired when a payment attempt fails. Receives an error object. |

sdk.components.create(type, options)

Creates a component instance. Call .mount(selector) to attach it to the DOM.

| Type | Description | | :--- | :---------- | | 'fs-card' | Card number, expiry, and CVV fields inside a secure iframe. | | 'fs-pay-button' | Submit button that triggers payment when clicked. | | 'fs-disclosures' | FastSpring reseller disclosure with auto-populated Privacy Policy and Terms of Sale links. |

fs-card options:

| Option | Type | Default | Description | | :----- | :--- | :------ | :---------- | | labelMode | 'fixed' | 'floating' | 'floating' | Label placement. 'floating' animates labels on focus; 'fixed' places them above each input. | | hideCardHeader | boolean | false | Hide the built-in "Payment" title row. | | style | object | | Style overrides. See Style Properties Reference. |

sdk.checkout(sessionId, callbacks)

Loads session data into the mounted components. The card and pay button become visible once the session is confirmed open.

sdk.checkout('<SESSION_ID>', {
  onSuccess: () => { /* checkout is ready */ },
  onError:   (error) => { /* session load failed */ },
});

Getting a session ID: Create a session server-side using the FastSpring Sessions API. Pass the returned id field here.

Styling

Every component accepts a style object organized by state and category:

sdk.components.create('fs-card', {
  style: {
    state: {
      default: {
        card:  { backgroundColor: '#fff', borderRadius: '8px', border: '1px solid #e5e7eb' },
        input: { height: '48px', borderColor: '#e5e7eb' },
      },
      focus: {
        input: { borderColor: '#2563eb' },
      },
      error: {
        input: { borderColor: '#dc2626' },
      },
    },
  },
});

For the full list of style properties, states, and drop-in presets for all three components, see the Style Properties Reference.

Examples

A complete working example — including HTML, SDK initialization, all three components, and a dark mode and minimal preset — is available in the FastSpring Checkout Components examples repo.

Documentation

• Set up Component Checkouts — configure your checkout in the FastSpring app
• Vanilla JS Integration Guide — step-by-step integration walkthrough
• Style Properties Reference — every style property for every component
• Sessions API — server-side session creation

License

MIT