Events

Sanwo emits events at each stage of the checkout lifecycle. Subscribe to events for analytics, logging, UI updates, or custom behavior.

Event types

Event	Description
started	Checkout initiated, iframe/webview about to render.
opened	Checkout UI is visible to the user.
loaded	Provider SDK finished loading inside the checkout.
success	Payment completed successfully.
cancelled	User dismissed the checkout.
failed	Payment failed.
closed	Checkout UI removed from DOM/view hierarchy.

Event flow

started → opened → loaded → success/cancelled/failed → closed

The loaded event fires after the provider’s SDK initializes inside the iframe or webview. The terminal events (success, cancelled, failed) are always followed by closed.

CheckoutEvent

Every event callback receives a CheckoutEvent object:

Field	Type	Description
type	string / enum	The event type (e.g. "success", "cancelled")
provider	string	The provider ID that raised the event
timestamp	number / Date / Long	When the event occurred
data	object? / Map?	Event-specific payload (e.g. reference on success)

CheckoutState

The checkout maintains an internal state machine. You can read the current state at any time.

State	Description
idle	No checkout in progress.
rendering	Checkout iframe/webview is being created.
opened	Checkout UI is visible.
successful	Payment succeeded (terminal).
cancelled	User cancelled (terminal).
failed	Payment failed (terminal).
closed	Checkout UI has been torn down.

Web / JavaScript

Subscribe with sanwo.on(), which returns an unsubscribe function. Remove a specific handler with sanwo.off(), or tear down everything with sanwo.destroy().

import { createSanwo } from "@sanwohq/web";
import { paystack } from "@sanwohq/paystack";

const sanwo = createSanwo({
  provider: paystack,
  publicKey: "pk_test_xxxxxxxxxxxx",
});

// Subscribe — returns an unsubscribe function
const unsubSuccess = sanwo.on("success", (event) => {
  console.log("Payment succeeded:", event.data.reference);
});

const unsubLoaded = sanwo.on("loaded", (event) => {
  console.log("Checkout loaded at", event.timestamp);
});

// Unsubscribe a single handler
unsubSuccess();

// Or use off() with the handler reference
function onFailed(event) {
  console.error("Payment failed:", event.data);
}
sanwo.on("failed", onFailed);
sanwo.off("failed", onFailed);

// Remove all listeners and clean up
sanwo.destroy();

API

Method	Signature	Description
sanwo.on	(event: string, handler: (event: CheckoutEvent) => void) => () => void	Subscribe. Returns unsubscribe function.
sanwo.off	(event: string, handler: Function) => void	Remove a specific handler.
sanwo.destroy	() => void	Remove all listeners, close checkout, clean up DOM.
sanwo.currentState	string (read-only)	Current checkout state.

React

Use the useSanwo() hook for event access. The sanwo instance from the hook has the same on/off API as the web SDK.

import { useSanwo } from "@sanwohq/react";
import { useEffect } from "react";

function PaymentTracker() {
  const { sanwo } = useSanwo();

  useEffect(() => {
    const unsub = sanwo.on("success", (event) => {
      analytics.track("payment_success", {
        ref: event.data.reference,
        provider: event.provider,
      });
    });
    return unsub;
  }, [sanwo]);

  return null;
}

React Native

Use the useSanwo() hook. It exposes on and off functions directly.

import { useSanwo } from "@sanwohq/react-native";
import { useEffect } from "react";

function PaymentTracker() {
  const { on, off } = useSanwo();

  useEffect(() => {
    const handler = (event) => {
      analytics.track("payment_success", {
        ref: event.data.reference,
        provider: event.provider,
      });
    };
    on("success", handler);
    return () => off("success", handler);
  }, [on, off]);

  return null;
}

API

Method	Signature	Description
on	(event: string, handler: (event: CheckoutEvent) => void) => void	Subscribe to an event.
off	(event: string, handler: Function) => void	Unsubscribe from an event.

Flutter

Use sanwo.on() to subscribe and sanwo.off() to unsubscribe. sanwo.removeAllListeners() clears everything.

import 'package:sanwo_flutter/sanwo_flutter.dart';
import 'package:sanwo_paystack/sanwo_paystack.dart';

final sanwo = Sanwo(
  provider: paystackProvider,
  publicKey: 'pk_test_xxxxxxxxxxxx',
);

// Subscribe
sanwo.on(SanwoEvent.success, (event) {
  print('Payment succeeded: ${event.data['reference']}');
});

sanwo.on(SanwoEvent.loaded, (event) {
  print('Checkout loaded at ${event.timestamp}');
});

sanwo.on(SanwoEvent.failed, (event) {
  print('Payment failed: ${event.data}');
});

// Remove a specific listener
sanwo.off(SanwoEvent.success, myCallback);

// Remove all listeners (e.g. in dispose())
sanwo.removeAllListeners();

API

Method	Signature	Description
sanwo.on	(SanwoEvent, Function(CheckoutEvent)) => void	Subscribe to an event.
sanwo.off	(SanwoEvent, Function) => void	Remove a specific handler.
sanwo.removeAllListeners	() => void	Remove all event listeners.

SanwoEvent enum

Value	Corresponding event
SanwoEvent.started	started
SanwoEvent.opened	opened
SanwoEvent.loaded	loaded
SanwoEvent.success	success
SanwoEvent.cancelled	cancelled
SanwoEvent.failed	failed
SanwoEvent.closed	closed

iOS / Swift

Subscribe with sanwo.on(). Calls are chainable (each returns self).

sanwo
    .on(.started) { event in
        print("Checkout started with provider: \(event.provider)")
    }
    .on(.loaded) { event in
        print("Provider SDK loaded")
    }
    .on(.success) { event in
        print("Paid! Ref: \(event.data?["reference"] ?? "")")
    }
    .on(.cancelled) { event in
        print("User cancelled")
    }
    .on(.failed) { event in
        print("Payment failed: \(event.data ?? [:])")
    }
    .on(.closed) { event in
        print("Checkout dismissed")
    }

API

Method	Signature	Returns	Description
sanwo.on	(_ event: SanwoEvent, handler: @escaping (CheckoutEvent) -> Void)	Self	Subscribe. Chainable.

SanwoEvent enum

.started, .opened, .loaded, .success, .cancelled, .failed, .closed

Android / Kotlin

Subscribe with sanwo.on(), which returns an unsubscribe function.

// Subscribe — returns an unsubscribe function
val unsubscribe = sanwo.on(SanwoEvent.SUCCESS) { event ->
    Log.d("Sanwo", "Paid! Ref: ${event.data?.get("reference")}")
}

sanwo.on(SanwoEvent.LOADED) { event ->
    Log.d("Sanwo", "Checkout loaded")
}

sanwo.on(SanwoEvent.FAILED) { event ->
    Log.e("Sanwo", "Payment failed: ${event.data}")
}

sanwo.on(SanwoEvent.CANCELLED) { event ->
    Log.d("Sanwo", "User cancelled")
}

// Unsubscribe later
unsubscribe()

API

Method	Signature	Returns	Description
sanwo.on	(event: SanwoEvent, handler: (CheckoutEvent) -> Unit)	() -> Unit	Subscribe. Returns unsubscribe function.

SanwoEvent constants

Constant	Corresponding event
SanwoEvent.STARTED	started
SanwoEvent.OPENED	opened
SanwoEvent.LOADED	loaded
SanwoEvent.SUCCESS	success
SanwoEvent.CANCELLED	cancelled
SanwoEvent.FAILED	failed
SanwoEvent.CLOSED	closed