Security
Security model, iframe isolation, and credential handling
Iframe Isolation
Each embedded component runs in a sandboxed iframe with strict isolation:
| Property | Description |
|---|---|
| Separate origin | Components cannot access the host page's DOM, cookies, or localStorage |
| CSP headers | frame-ancestors restricts which pages can embed the iframe |
| Origin validation | Only registered origins receive postMessage communication |
| Sandbox attributes | allow-scripts allow-same-origin allow-forms allow-popups |
Credential Delivery
Credentials are exchanged between host and iframe exclusively through postMessage — never in URL parameters, localStorage, or the iframe src attribute.
Iframe ready
SDK waits for IFRAME_READY postMessage from the component iframe before sending any data.
Credential delivery
SDK sends AUTH_CREDENTIALS via postMessage with instance-scoped routing.
Acknowledgment
Iframe confirms with AUTH_CREDENTIALS_ACK before mounting the component UI.
Mid-session refresh
Iframe signals AUTH_EXPIRED; SDK calls the configured refresh function and delivers fresh credentials via AUTH_CREDENTIALS_REFRESH.
Failure handling
If refresh fails, state transitions to ERROR; the auth_token_refresh_failed event fires via onEvent, and onError fires with code AUTH_FAILED.
Authentication Strategies
The SDK supports four strategies: OAuth (recommended), Session, Client Secret, and API Key.
For full configuration examples and type definitions for each strategy, see the Authentication API Reference.
| Strategy | Best for | Tradeoffs |
|---|---|---|
| OAuth | Most production integrations | Requires token endpoint; handles refresh automatically |
| Session | Same-origin apps with existing auth | Unreliable cross-origin due to third-party cookie restrictions |
| Client Secret | Server-rendered pages, dev | Secret exposed to client; requires rotation |
| API Key | Simple integrations, prototyping | Static; no rotation; lowest security |
Content Security Policy
If your host page uses a Content Security Policy, add these directives:
frame-src https://runtime.embed.visa.com https://*.runtime.embed.visa.com;
script-src https://sdk.embed.visa.com;
connect-src https://api.embed.visa.com;For development environments, also allow:
frame-src https://local.runtime.embed.visa.com:8081;
script-src https://local.sdk.embed.visa.com:8081;Security Properties
- Credentials are never placed in iframe URL params or
localStorage - All
postMessagepayloads includeinstanceIdfor instance-scoped routing - Messages are validated against a registered origin allowlist
- HttpOnly cookies prevent JavaScript access to session credentials (session strategy)
- The SDK script itself makes no network requests — all API calls happen inside the iframe
- Card data and PII never leave the iframe boundary