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
FastSpring.init() callbacksRegister 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
| Field | Type | Description |
|---|---|---|
sessionId | string | The session ID |
status | string | Session status: OPEN, EXPIRED, CANCELLED, PENDING_ORDER, COMPLETED or FAILED; may be null |
locale | string | Session locale |
country | string | Country code |
currency | string | Currency code (e.g. "USD") |
cart | object | Cart 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 |
warnings | array | Session warnings, each with code and message |
Line item fields (cart.lineItems here, and lineItems in onOrderCompleted)
| Field | Type | Description |
|---|---|---|
productPath | string | Product path (product ID) |
productType | string | Product type; may be null |
quantity | number | Quantity |
displayName | string | Product display name; may be null |
unitNetPrice | number | Unit price after discounts (also unitNetPriceDisplay) |
unitListPrice | number | Unit list price (also unitListPriceDisplay) |
unitDiscount | number | Discount per unit (also unitDiscountDisplay) |
extendedNetTotal | number | Line total (also extendedNetTotalDisplay) |
taxAmount | number | Tax for the line (also taxAmountDisplay) |
taxPercent | number | Tax rate for the line |
subscription | object | intervalUnit, intervalLength and trialDays for subscription products; null otherwise |
Fired each time the session reloads after a change the customer makes in the browser, such as entering a postal code, applying or removing a coupon, or changing country or currency. It does not fire for the first load (use onSessionLoaded) or when the order completes (use onOrderCompleted). Changes you make on your server through the Sessions API do not fire it.
const sdk = FastSpring.init({
checkoutUrl: '...',
onSessionUpdated: (data) => {
document.querySelector('#order-total').textContent = data.cart.withTaxNetTotalDisplay;
},
});data has the same fields as onSessionLoaded. It doesn't say which fields changed, so re-render every value you display.
Fired when the customer clicks any pay button: the Pay Button, a saved payment method button, or a wallet button such as Apple Pay or Google Pay. It fires on the click itself, before validation and before the order is created, even if the payment then stops. Use it for reporting only: the return value is ignored and the payment continues either way.
const sdk = FastSpring.init({
checkoutUrl: '...',
onPayClicked: (data) => {
console.log('Pay clicked:', data.paymentMethodType, data.oneClick);
},
});View data object
| Field | Type | Description |
|---|---|---|
paymentMethodType | string | Payment method of the button clicked (e.g. "card", "paypal", "applepay", "googlepay") |
oneClick | boolean | true when the customer used a saved payment method |
session | object | The current session, with the same fields as onSessionLoaded; null if no session has loaded yet |
Fired after a successful payment and order completion.
const sdk = FastSpring.init({
checkoutUrl: '...',
onOrderCompleted: (data) => {
window.location.href = `/confirmation?order=${data.order.orderId}`;
},
});View data object
| Field | Type | Description |
|---|---|---|
order | object | Order summary: orderId, orderReference, paymentMethodType, cardScheme, cardLast4, paymentMethodDisplay and items (each with productPath and quantity) |
currency | string | Currency code |
withoutTaxNetTotal | number | Order total excluding tax (also withoutTaxNetTotalDisplay) |
withTaxNetTotal | number | Order total including tax (also withTaxNetTotalDisplay) |
taxTotal | number | Tax total (also taxTotalDisplay) |
discountTotal | number | Discount total (also discountTotalDisplay) |
couponCode | string | Applied coupon code, or null |
lineItems | array | Line items in the completed order |
Fired when a payment attempt is rejected or encounters an error. The checkout stays open, so the customer can correct their details and try again.
const sdk = FastSpring.init({
checkoutUrl: '...',
onPaymentFailed: (error) => {
document.querySelector('#error-message').textContent =
'Payment failed. Please check your card details and try again.';
},
});
onPaymentFailedfires on payment rejection, not on session load failure. For session load errors, use theonErrorcallback onsdk.checkout().
View error object
| Field | Type | Description |
|---|---|---|
type | string | Failure category: "card_declined", "insufficient_funds", "invalid_card_data", "expired_card", "payment_method_error", "validation_error", "processing_error", "fraud_blocked" or "unknown" |
code | string | Machine-readable code for logging and analytics. Raw processor decline codes are never included. |
message | string | Localized error description that is safe to show the customer |
retryable | boolean | Included only when FastSpring knows whether retrying can succeed. If it's missing, treat it as unknown, not false. |
paymentMethodType | string | Payment method used for the attempt; may be null |
sdk.checkout() callbacks
sdk.checkout() callbacksRegister 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.');
},
});Fired when the session fails to load.
sdk.checkout('<SESSION_ID>', {
onError: (error) => {
console.error('Session load failed:', error);
},
});View error object
| Field | Type | Description |
|---|---|---|
type | string | Error type |
message | string | Human-readable error description |
Common causes:
- Session ID is invalid or malformed
- Session has already been used
- Session has expired
Create a fresh session immediately before each
sdk.checkout()call. Sessions are single use and expire, so pre-creating or reusing them is the most common cause of this error.