Before you can test the KYC Widget in Sandbox or Production, Uphold must complete a one-time internal setup to enable identity verification for your account. Contact your Account Manager to have this provisioned ahead of your integration.
The KYC Widget runs against a session — a short-lived, server-side authorization scoped to one flow and one user. Create it server-side using your OAuth credentials.
Never call the Create Session endpoint from the client. Your Client Secret must not leave your backend.
Call POST /widgets/kyc/sessions with the verify flow and, optionally, the processes you want the user to complete:
Pass response.session to your frontend (e.g. as part of your page response or via your own API endpoint). The SDK takes it as a single session argument.
On the frontend, instantiate KycWidget with the session from Step 3, then mount it into a container element.
import { KycWidget } from '@uphold/enterprise-kyc-widget-web-sdk';// session is the `session` property from the backend response in Step 3const widget = new KycWidget(session, { theme: { appearance: 'dark' }, // omit to follow system preference debug: true // verbose logging during development});widget.mountIframe(document.getElementById('kyc-container'));
The container must have explicit CSS width and height — the iframe fills its bounds. Minimum recommended size is 400px × 600px.
The complete event signals that the user has submitted all required processes. Final verification outcomes (e.g. identity approved or rejected) are delivered asynchronously via KYC webhooks.
With your Sandbox credentials and the Sandbox Widget host configured, run through this checklist:
The Widget mounts and ready fires.
Completing the verification flow fires complete.
Closing or dismissing the Widget fires cancel.
The browser console shows no CSP violations (look for “Refused to frame”).
Once Sandbox is green, swap your OAuth credentials to Production. The Widget host is selected automatically by the session url returned from your backend — no client-side environment switching is needed.
Native mobile apps embed the Widget through a WebView that loads an HTML page hosting the SDK. Events flow between native code and the WebView through a JavaScript bridge.The setup is the same as the web flow above — install the SDK in your JS bundle, create the session on your backend, and instantiate KycWidget. The only addition is the bridge that forwards events to native code.
Bundle this HTML with your app and load it in the WebView. The sendToNativeApp helper at the bottom forwards events to whichever bridge is available (iOS, Android, or React Native).
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>KYC Widget</title> <style> body { margin: 0; padding: 0; } #kyc-container { width: 100%; height: 100vh; } </style> </head> <body> <div id="kyc-container"></div> <!-- Include your JS bundle which contains the SDK --> <script src="your-bundle-with-sdk.js"></script> <script> window.addEventListener('load', () => { const session = createKycWidgetSession(); const widget = new KycWidget(session); widget.on('complete', () => { sendToNativeApp('complete'); widget.unmount(); }); widget.on('cancel', () => { sendToNativeApp('cancel'); widget.unmount(); }); widget.on('error', (event) => { sendToNativeApp('error', event.detail.error); widget.unmount(); }); widget.mountIframe(document.getElementById('kyc-container')); }); function sendToNativeApp(type, data = null) { const message = { type, data }; if (window.webkit?.messageHandlers?.kycWidgetMessage) { window.webkit.messageHandlers.kycWidgetMessage.postMessage(message); } else if (window.KycBridge) { window.KycBridge.onMessage(JSON.stringify(message)); } else if (window.ReactNativeWebView) { window.ReactNativeWebView.postMessage(JSON.stringify(message)); } } </script> </body></html>
The SDK must be included in your WebView bundle (e.g. via your build pipeline). Loading it from a CDN is not supported.
The most common SDK options. See the SDK reference for the full schema and all event types.
Option
Purpose
theme
Customize the Widget’s appearance: force light or dark mode, set brand colors, typography, and per-component border radii. See KycTheme for all options.
Widget not displayingConfirm the Widget host for your environment is in the frame-src directive of your CSP (see Step 2). Open DevTools → Console and look for Refused to frame violations.Container is empty after mountThe iframe fills its container — the container must have explicit CSS width and height. Minimum recommended size is 400px × 600px.Events not firing in native appsVerify that:
JavaScript is enabled in the WebView.
The message bridge is registered before the HTML page loads.
Event handler names match the platform-specific bridge contract used in sendToNativeApp.
Widget never unmounts. The SDK does not auto-unmount. Call widget.unmount() from each terminal handler (complete, cancel, error).