Skip to main content

​
Events

The SDK reports every step of the purchase flow as:
  1. DOM custom events — bubble up from each <khaime-*> component, composed across Shadow DOM. Listen with addEventListener.
  2. SDK callbacks — registered via sdk.on({ … }). Easier when you’ve initialized the SDK programmatically.
Both fire for the same underlying action. Pick whichever fits your integration.

​
Two ways to listen

// Option A — callbacks (global)
sdk.on({
  onAddToCart: (product, quantity) => { /* … */ },
  onPaymentSuccess: (result) => { /* … */ },
});

// Option B — DOM events (per component)
document.addEventListener('khaime:payment-success', (e) => {
  console.log(e.detail.orderId);
});
Every event detail includes timestamp (ms since epoch) and merchantId.

​
Purchase-flow events

​
khaime:product-click

Fired when a customer clicks a product card or tile. 
{
  product: Product;
  source: 'grid' | 'card' | 'detail';
  timestamp: number;
  merchantId: string | number;
}
Callback: onProductClick(product)

​
khaime:add-to-cart

Fired when a customer adds an item to the cart. 
{
  product: Product;
  quantity: number;
  variant?: { id: number; name: string };
  timestamp: number;
  merchantId: string | number;
}
Callback: onAddToCart(product, quantity)

​
khaime:cart-updated

Fired on every cart mutation — add, remove, quantity change, clear, or hydrate from storage. 
{
  items: LocalCartItem[];
  itemCount: number;
  subtotal: number;              // minor units
  action: 'add' | 'remove' | 'update' | 'clear' | 'hydrate';
  timestamp: number;
  merchantId: string | number;
}
Callback: onCartUpdated(items, action) Use this to update a header badge, drawer count, or analytics.

​
khaime:cart-open / khaime:cart-close

Fired when the cart drawer (or cart page) opens or closes. Callbacks: onCartOpen(), onCartClose()

​
khaime:currency-change

Fired when the customer picks a different currency from the switcher. 
{
  previousCurrency: string;
  newCurrency: string;
  timestamp: number;
  merchantId: string | number;
}
Callback: onCurrencyChange(newCurrency)

​
khaime:checkout-init

Fired right after the SDK creates a checkout session (before the payment modal opens). 
{
  productId: number;
  amount: number;       // minor units
  currency: string;
  sessionToken?: string;
  timestamp: number;
  merchantId: string | number;
}
Callback: onCheckoutInit(sessionToken) Use this to log checkout starts for funnel analysis.

​
khaime:payment-success

Fired after the customer’s payment is confirmed. 
{
  sessionToken: string;
  orderId?: string;
  amount: number;                       // minor units
  currency: string;
  paymentMethod: 'stripe' | 'paystack';
  timestamp: number;
  merchantId: string | number;
}
Callback: onPaymentSuccess(result)
This event confirms the payment UI completed — not that the charge settled. Always verify via a webhook before fulfilling the order.

​
khaime:payment-error

Fired when the payment fails (declined card, expired session, gateway error, etc.). 
{
  error: string;          // human-readable message
  code?: string;          // gateway error code, if available
  sessionToken?: string;
  timestamp: number;
  merchantId: string | number;
}
Callback: onPaymentError(error)

​
Full callback signature

All purchase-related callbacks accepted by sdk.on(…): 
sdk.on({
  onProductClick?:   (product: Product) => void;
  onAddToCart?:      (product: Product, quantity: number) => void;
  onCartUpdated?:    (items: LocalCartItem[], action: string) => void;
  onCartOpen?:       () => void;
  onCartClose?:      () => void;
  onCurrencyChange?: (newCurrency: string) => void;
  onCheckoutInit?:   (sessionToken: string) => void;
  onPaymentSuccess?: (result: PaymentSuccessEventDetail) => void;
  onPaymentError?:   (error: PaymentErrorEventDetail) => void;
});
Callbacks are additive — calling sdk.on(...) multiple times merges into the existing handler map (later calls override same-named keys).

​
Analytics example

Wire every purchase step into your analytics tool: 
sdk.on({
  onProductClick: (p) => analytics.track('Product Viewed', {
    productId: p.id, name: p.title, price: p.price,
  }),
  onAddToCart: (p, qty) => analytics.track('Product Added', {
    productId: p.id, quantity: qty, value: p.price * qty,
  }),
  onCheckoutInit: (sessionToken) => analytics.track('Checkout Started', {
    sessionToken,
  }),
  onPaymentSuccess: ({ orderId, amount, currency, paymentMethod }) => {
    analytics.track('Order Completed', { orderId, revenue: amount / 100, currency, paymentMethod });
  },
  onPaymentError: ({ error, code }) => analytics.track('Payment Failed', { error, code }),
});

​
See also