Web SDK events reference

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().

Billing.initMethod() and the Billing.stripe methods don’t emit events. They report the same moments through callbacks in their options.

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

success

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.

string

The ID of the order in FunnelFox Payments.

string

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"
});

error

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.

Payment declines don’t fire error. The checkout shows the decline message to the buyer. To read the decline in your code, listen for purchase-failure.

Example:

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

status-change

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.

destroy

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.

purchase-failure

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.

string

The failure message.

string | null

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

string | null

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

Example:

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);
  }
});

checkout.on('purchase-failure', error => {
  if (error.declineCode) {
    console.log('Declined:', error.declineCode, error.declineCodeSource);
  }
});

In TypeScript, pass EVENTS.PURCHASE_FAILURE instead of the string, and type the handler argument with a cast. The event isn’t in the CheckoutEventName type, so the string doesn’t compile.

Tax updates

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

API reference

Webhook reference

Billing Web SDK

Web SDK events reference

success

error

status-change

destroy

purchase-failure

Tax updates

​success

​error

​status-change

​destroy

​purchase-failure

​Tax updates

success

error

status-change

destroy

purchase-failure

Tax updates