Debug with events
The onEvent stream, and the unavailable event.
onEvent — every shape it can send
onEvent is a debug stream, not a payment signal — use the callbacks on open() for that. Every event carries sessionId:
type | When |
|---|---|
open | open() was called and the sheet is about to show. |
alive | The document loaded and ran scripts. |
ready | The payment block is on screen. |
resize | { height } — reported, but nothing here is sized by it. |
gateway | The page is navigating this WebView to a gateway. |
handoff | { scheme } — a bank/wallet deeplink was handed to the OS. |
handoff_failed | { scheme } — the OS had nothing registered to open it. |
load_timeout | { stage: 'alive' | 'ready' } — a load deadline elapsed. |
load_error | The WebView itself failed to load the page. |
unavailable | { reason } — the session cannot be paid at all. See below. |
settled | { outcome } — the sheet's one outcome, mirrors what open() resolved with. |
Turn on debug to forward the page's console output to your own console, with redaction.
unavailable is an event, not a callback
onUnavailable does not exist on open(). When the session cannot be paid at all — 'not-found', 'expired', 'spent', 'no-customer', 'no-methods', 'load-failed' — the page renders its own explanation and the buyer dismisses the sheet, which settles as onClose. Routing it through onFailure would tell your app a payment was attempted and rejected, when none was.
Catch it via onEvent({ type: 'unavailable', reason }) if you want to log why a buyer saw an empty sheet. It is usually a sign your own integration created the session wrong — most often an expired or already-used id, or, specific to this SDK, 'no-customer': the session was created with no buyer attached, which this package has no field to supply after the fact.