The ID of the order in FunnelFox Payments.
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 |
success
Section titled “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.
orderIdstringstatusstringThe 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);});status-change
Section titled “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
Section titled “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
Section titled “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.
messagestringThe failure message.
declineCodestring | nullThe decline code in uppercase, for example "INSUFFICIENT_FUNDS". Learn more
about decline codes.
declineCodeSourcestring | nullThe 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); }});Tax updates
Section titled “Tax updates”Tax updates come through the onTaxChange, onTaxPending, and onTaxError
callbacks, which are fully typed. Learn more about
taxes in the Web SDK.