Skip to main content
The Billing SDK’s checkout process emits several events that you can handle to respond to different stages of the payment flow. You can attach event listeners or you may use the callback options in createCheckout for the same events.
Learn more about CheckoutInstance.
Below is a list of all checkout events and their meanings:

​
success

When it fires: When a payment is completed successfully and the checkout has finished. This usually means the customer’s payment was processed and a subscription or purchase was created. Data: The event handler receives a PaymentResult object which includes details about the completed transaction.
​
orderId
string
The ID of the order/subscription created on Funnelfox.
​
status
string
The status string (e.g. "succeeded" for a successful payment).
​
transactionId
string
The transaction identifier (if applicable, e.g. from the payment processor).
Example: 
checkout.on('success', (result) => {
  console.log('Payment successful, Order ID:', result.orderId);
  console.log('Status:', result.status);       // e.g. "succeeded"
  console.log('Transaction ID:', result.transactionId);
});

​
error

When it fires: When an error occurs during the checkout or the payment fails. Data: The handler receives an Error object (which could be one of the SDK’s specific error types like ValidationError, APIError, etc.). You can inspect error.message for a human-readable message. Depending on the error type, other properties may be available:
​
message
string
A human-readable error message.
​
code
string
A short error code string, if provided (e.g. "invalid_price").
​
requestId
string
An ID for the request/transaction, useful when contacting support.
Example: 
checkout.on('error', (error) => {
  console.error('Checkout error:', error.message);
  if (error.code) {
    console.error('Error code:', error.code);
  }
  if (error.requestId) {
    console.error('Request ID:', error.requestId);
  }
});

​
status-change

When it fires: Whenever the checkout’s internal state changes. For example, the checkout might move from "initializing" to "ready" once it’s fully loaded, then to "processing" when the user submits payment, and finally to "completed" or "error". Data: The handler is called with two arguments: newState and oldState (both strings). States include "initializing", "ready", "processing", "action_required", "completed", and "error". 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 the checkout instance has been destroyed. This can happen if you call checkout.destroy() or if the checkout cleans up after completion. 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, you would create a new checkout instance.
⌘I