Callbacks

Reference for every SDK callback — when each fires, what data it receives, and how they sequence.

Callbacks are how you connect the checkout lifecycle to your own UI: showing a loading state while the session loads, redirecting after a completed order, or displaying an error message when payment fails. This page documents every callback the SDK exposes, where to register each one, and the shape of the data they receive.

Callback order

In a typical integration, callbacks fire in this sequence:

sdk.checkout() → onSuccess

The session loaded successfully. The checkout is ready, and the Card and Pay Button are now visible and accepting input.

FastSpring.init() → onSessionLoaded

Session data (cart, totals, currency, warnings) is now available. Use this to update your UI, such as hiding a loading spinner or displaying an order summary.

FastSpring.init() → onSessionUpdated

Fires each time the session reloads after the customer changes something in the browser, such as applying a coupon or changing country. It can fire any number of times, or not at all. Use it to keep your order summary current.

FastSpring.init() → onPayClicked

The customer clicked a pay button. This fires before validation and before the order is created.

FastSpring.init() → onOrderCompleted or onPaymentFailed

After the customer clicks Pay, one of two things happens:

  • onOrderCompleted: payment succeeded. Redirect to a confirmation page or show a success state.
  • onPaymentFailed: payment was rejected. Display an error message. The checkout stays open so the customer can try again.

FastSpring.init() callbacks

Register these when initializing the SDK. They remain active for the lifetime of the sdk instance.

Fired when session data has been fetched and the checkout is ready for input.

const sdk = FastSpring.init({
    checkoutUrl: '...',
    onSessionLoaded: (data) => {
        document.querySelector('#loading-spinner').hidden = true;
    },
});
View data object
FieldTypeDescription
sessionIdstringThe session ID
statusstringSession status: OPEN, EXPIRED, CANCELLED, PENDING_ORDER, COMPLETED or FAILED; may be null
localestringSession locale
countrystringCountry code
currencystringCurrency code (e.g. "USD")
cartobjectCart contents: couponCode, couponApplied, lineItems (line items in the session), taxRate, and the totals listTotal, discountTotal, taxTotal, withoutTaxNetTotal and withTaxNetTotal, each with a matching ...Display string
warningsarraySession warnings, each with code and message

Line item fields (cart.lineItems here, and lineItems in onOrderCompleted)

FieldTypeDescription
productPathstringProduct path (product ID)
productTypestringProduct type; may be null
quantitynumberQuantity
displayNamestringProduct display name; may be null
unitNetPricenumberUnit price after discounts (also unitNetPriceDisplay)
unitListPricenumberUnit list price (also unitListPriceDisplay)
unitDiscountnumberDiscount per unit (also unitDiscountDisplay)
extendedNetTotalnumberLine total (also extendedNetTotalDisplay)
taxAmountnumberTax for the line (also taxAmountDisplay)
taxPercentnumberTax rate for the line
subscriptionobjectintervalUnit, intervalLength and trialDays for subscription products; null otherwise

sdk.checkout() callbacks

Register these per sdk.checkout() call. They fire once for that session load attempt.

Fired when the session loads successfully and the checkout is ready for input. No arguments.

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