Skip to content

Web SDK events reference

Events a FunnelFox Payments Web SDK checkout emits: success, errors, state changes, destroy, and failed payment attempts.

A checkout created with createCheckout() emits events at each stage of the payment flow. Subscribe with checkout.on(eventName, handler), or pass the matching callback to createCheckout().

Event Callback in createCheckout()
success onSuccess
error onError
status-change onStatusChange
destroy onDestroy
purchase-failure None

When it fires: When a payment is completed successfully. The customer’s payment was processed and a subscription or purchase was created.

Data: The handler receives a PaymentResult object.

orderIdstring

The ID of the order in FunnelFox Payments.

statusstring

The status string ("succeeded" for a successful payment).

Example:

checkout.on('success', result => {
console.log('Payment successful, Order ID:', result.orderId);
console.log('Status:', result.status); // "succeeded"
});

When it fires: When the checkout fails to initialize, or when updatePrice() fails.

It also fires with no argument when the buyer selects a payment method or starts a payment. Use that call to clear an error message you show.

Data: An Error object, or undefined. Inspect error.message for a human-readable message. Learn more about error classes.

Example:

checkout.on('error', error => {
if (!error) {
hideErrorMessage(); // A new payment attempt started
return;
}
console.error('Checkout error:', error.message);
});

When it fires: Whenever the checkout’s state changes. For example, the checkout moves from "initializing" to "ready" once it’s loaded, then to "processing" when the user submits payment, and to "completed" or "error".

Data: The handler is called with two arguments: newState and oldState. States include "initializing", "ready", "processing", "action_required", "updating", "completed", "error", and "destroyed". Learn more about checkout states.

Example:

checkout.on('status-change', (newState, oldState) => {
console.log(`State changed: ${oldState} -> ${newState}`);
if (newState === 'completed') {
console.log('Checkout completed successfully!');
}
});

This event is useful for updating UI elements or logging analytics at different stages of the checkout.

When it fires: When you call checkout.destroy().

Data: No additional data (the handler is simply called with no arguments).

Example:

checkout.on('destroy', () => {
console.log('Checkout instance was destroyed and cleaned up.');
});

Once this event fires, the checkout UI has been removed from the DOM. If the user needs to pay again, create a new checkout instance.

When it fires: When a payment attempt fails, for example when the bank declines the card.

Data: An Error. When FunnelFox Payments reports a decline, the error also carries declineCode and declineCodeSource. Failures inside Primer, such as a tokenization or 3DS error, have no decline code.

messagestring

The failure message.

declineCodestring | null

The decline code in uppercase, for example "INSUFFICIENT_FUNDS". Learn more about decline codes.

declineCodeSourcestring | null

The provider that reported the decline: "primer", "stripe", or "adyen".

Example:

TypeScript
import { EVENTS } from '@funnelfox/billing';
import type { PaymentFailure } from '@funnelfox/billing';
checkout.on(EVENTS.PURCHASE_FAILURE, error => {
const failure = error as PaymentFailure;
if (failure.declineCode) {
console.log('Declined:', failure.declineCode, failure.declineCodeSource);
}
});

Tax updates come through the onTaxChange, onTaxPending, and onTaxError callbacks, which are fully typed. Learn more about taxes in the Web SDK.