State Machine
Component instance states and valid transitions.
States
Every embedded component instance has a state accessible via instance.getState():
| State | Description |
|---|---|
INITIALIZING | render() called, iframe being created |
MOUNTED | Iframe appended to DOM, waiting for IFRAME_READY |
CREDENTIAL_DELIVERED | Auth credentials sent to iframe (non-session strategies) |
AUTH_REQUIRED | Component needs authentication |
AUTH_IN_PROGRESS | Login popup is open or credential exchange is in flight |
AUTHENTICATED | Component is fully loaded and operational |
TOKEN_REFRESH_IN_PROGRESS | Token expired, refresh callback running |
ERROR | Unrecoverable error occurred |
DESTROYED | Terminal state — instance torn down |
Transition Diagram
┌──────────────┐
│ INITIALIZING │
└──────┬───────┘
│
▼
┌──────────┐ ┌──────────────────────┐
│ MOUNTED │────────→│ CREDENTIAL_DELIVERED │
└────┬─────┘ └──────────┬───────────┘
│ │
│ ┌─────────────────────┘
▼ ▼
┌───────────────┐ ┌─────────────────┐
│ AUTH_REQUIRED │────→│ AUTH_IN_PROGRESS │
└───────────────┘ └────────┬────────┘
│
▼
┌───────────────┐
┌──────→│ AUTHENTICATED │←──────┐
│ └───────┬───────┘ │
│ │ │
│ (token expires) │
│ ▼ │
│ ┌───────────────────────────┐ │
│ │TOKEN_REFRESH_IN_PROGRESS │─┘
│ └───────────────────────────┘
│
│ (refresh fails)
│ ▼
┌─────────┐
│ ERROR │
└────┬────┘
│
▼
┌───────────┐
│ DESTROYED │
└───────────┘Listening to State Changes
Use the onEvent callback to react to state transitions:
VisaAcceptance.init({
onEvent: (type, payload) => {
switch (type) {
case 'component_create':
showLoadingSpinner();
break;
case 'component_ready':
hideLoadingSpinner();
break;
case 'auth_required':
showLoginPrompt();
break;
case 'component_error':
showErrorState(payload.error);
break;
}
},
});Polling State
For imperative checks, use getState():
const instance = VisaAcceptance.render('transactions', '#container');
// Check state after a delay
setTimeout(() => {
const state = instance.getState();
if (state === 'ERROR') {
instance.destroy();
showFallbackUI();
}
}, 10000);Once an instance reaches DESTROYED, it cannot be reused. Call render() again to create a new instance.