Troubleshooting
Common issues and solutions for the Visa Acceptance SDK
Component Not Loading
Symptom: The container element remains empty after calling render().
Causes:
- SDK not initialized — call
init()beforerender() - Invalid container selector — verify the DOM element exists before
render() - Same-origin conflict — iframe and host cannot share the same origin
Use the browser DevTools console to check for [VisaAcceptance] prefixed warnings — these indicate the specific failure reason.
Authentication Failures
Symptom: Component shows authentication error or AUTH_REQUIRED event fires repeatedly.
Causes:
- Expired session cookies — user needs to re-authenticate
- Invalid token from
getToken()callback — verify token format and expiry - Third-party cookie blocking (Safari, privacy mode) — switch to
oauthstrategy
Iframe Height Issues
Symptom: Component renders but is cut off or has extra whitespace.
Causes:
- Container element has fixed height — use
min-heightinstead - CSS
overflow: hiddenon a parent element — check ancestor styles - Content still loading — wait for the
component_readyevent
Theme Not Applying
Symptom: Component ignores the theme preset or custom colors.
Causes:
- Unknown preset name — use one of:
anet,shadcn,corporate,perplexity,amethyst,bubblegum,shopify - Invalid OKLCH values — verify color format matches
oklch(L C H) - Theme can be updated at any time via
updateConfig()orinstance.updateTheme()
Console Warnings
| Warning | Meaning | Fix |
|---|---|---|
Ignored message from untrusted origin: | PostMessage received from unregistered origin | Register your domain with the Acceptance Platform team |
SDK already initialized... | init() called more than once | Call init() once; use updateConfig() for changes |
Unknown component: '{name}'... | Invalid component name passed to render() | Check ComponentName type for valid values |
SDK not initialized... | render() called before init() | Ensure init() completes before any render() call |
Unknown theme preset: {name} | Preset name not recognized | Use a valid preset name |
Cannot mount: iframe and host share the same origin. | Security violation | Verify SDK script URL points to a different domain |
If you see Cannot mount: iframe and host share the same origin, this is a hard security constraint. The SDK script must be loaded from a different origin than your host page.