Listening to Events
We strongly recommend using one of the Opal SDKs to receive typed events and lifecycle callbacks. The SDKs provideonEvent
, onOpen
, and onExit
handlers and expose a small enum of well-known events under OpalEventType
for convenience (e.g., SESSION_STARTED
, SESSION_COMPLETED
).
Each Opal mode (identity_verification
, connect
, card_connect
, account_verification
, transactions
) emits a set of mode‑specific events in addition to default session events. See below for structure, a complete list, and examples.
Event Structure
All Opal events follow a consistent structure:Event fields
Field | Type | Description |
---|---|---|
type | string | Fully qualified event name: <flow>.<object>.<action> or opal.session.<action> for default session events. |
mode | string | The active operational mode (e.g., connect , identity_verification , account_verification , transactions ). |
object | string | The related object (e.g., session , flow , step , identity , card , accounts ). |
action | string | The action that occurred (e.g., started , completed , verified , errored ). |
timestamp | string | ISO 8601 timestamp of when the event occurred. |
data | object | null | Additional context that varies by event type; may be null for lifecycle events. |
Possible flows:
identity_verification
connect
account_verification
transactions
Sample Events
opal.session.started
opal.session.errored
connect.flow.completed
Event Categories
Default session events (always available)
opal.session.started
- Opal UI opened and session beganopal.session.completed
- User completed the flow successfullyopal.session.errored
- A recoverable or terminal error occurredopal.session.exited
- User exited or dismissed Opal
Generic flow and step events
Emitted in addition to the default session events. These mirror the active mode‑specific events but are prefixed withopal
and can be emitted for any mode.
Flow
opal.flow.started
- A sub‑flow of Opal started (e.g., identity verification, account selection, verification).opal.flow.completed
- A sub‑flow of Opal completed. This does not always signify the end of the session; useopal.session.completed
to detect when Opal is fully completed.
Step
opal.step.started
- A new step started (e.g., phone input, card selection, CVV input).opal.step.completed
- A step completed and the next page is opening.
- Additional mode-specific events may be introduced over time. Your handler should use the
OpalEventType
enum to handle the specific cases you need.
All Event Types
The following table lists all currently supported event types with theirOpalEventType
mapping, and when they are typically emitted.
Event (OpalEventType - type) | When you might see it |
---|---|
SESSION_STARTED - opal.session.started | Opal UI opened and session began. |
SESSION_COMPLETED - opal.session.completed | User completed the overall Opal flow successfully. |
SESSION_ERRORED - opal.session.errored | A recoverable or terminal error occurred. |
SESSION_EXITED - opal.session.exited | User closed or dismissed Opal before completion. |
FLOW_STARTED - opal.flow.started | A sub-flow (for any mode) started. |
FLOW_COMPLETED - opal.flow.completed | A sub-flow (for any mode) completed. |
STEP_STARTED - opal.step.started | A step (screen) started. |
STEP_COMPLETED - opal.step.completed | A step (screen) completed. |
IDV_FLOW_STARTED - identity_verification.flow.started | Identity Verification flow started. |
IDV_STEP_STARTED - identity_verification.step.started | A step in Identity Verification started. |
IDV_STEP_COMPLETED - identity_verification.step.completed | A step in Identity Verification completed. |
IDV_FLOW_COMPLETED - identity_verification.flow.completed | Identity Verification flow completed. |
IDV_VERIFICATION_COMPLETED - identity_verification.identity.completed | Identity successfully verified (KYC passed). |
CXN_FLOW_STARTED - connect.flow.started | Connect flow started. |
CXN_STEP_STARTED - connect.step.started | A step in Connect started. |
CXN_STEP_COMPLETED - connect.step.completed | A step in Connect completed. |
CXN_FLOW_COMPLETED - connect.flow.completed | Connect flow completed. |
CXN_ACCOUNTS_SELECTED - connect.accounts.selected | User selected one or more accounts to connect. |
AVF_FLOW_STARTED - account_verification.flow.started | Account Verification flow started. |
AVF_STEP_STARTED - account_verification.step.started | A step in Account Verification started. |
AVF_STEP_COMPLETED - account_verification.step.completed | A step in Account Verification completed. |
AVF_FLOW_COMPLETED - account_verification.flow.completed | Account Verification flow completed. |
AVF_CARD_VERIFIED - account_verification.card.verified | Card verified successfully. |
TXN_FLOW_STARTED - transactions.flow.started | Transactions flow started. |
TXN_STEP_STARTED - transactions.step.started | A step in Transactions started. |
TXN_STEP_COMPLETED - transactions.step.completed | A step in Transactions completed. |
TXN_FLOW_COMPLETED - transactions.flow.completed | Transactions flow completed. |
TXN_ACCOUNTS_LINKED - transactions.accounts.linked | Accounts linked and subscribed for transactions. |
Data Payloads
The following events always include a non-nullevent.data
payload:
identity_verification.identity.completed
connect.accounts.selected
account_verification.card.verified
transactions.accounts.linked
Enhanced Event Handling
Using the JavaScript SDK
PostMessage Communication
For applications not using the Opal SDKs, you can listen to events via PostMessage:Setup PostMessage Listener
Best Practices
Event Handling
- Always verify event origins for security
- Use event filtering to reduce noise
- Implement proper error handling for all events
- Log events for debugging and analytics
Security
- Validate all event data before processing
- Never trust client-side events for critical business logic