Skip to main content
By the end of this guide the KYC Widget will be running in your app, mounted to a container, and emitting events you can react to.

Before you start

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.
You’ll need:
  • Access to the Widgets API to create widget sessions. Manage your access in the Enterprise Portal.
  • A backend that can call the Widgets API to create sessions on behalf of your users.
  • A frontend — either a web app (iframe) or a native app (WebView) — to embed the Widget.
The Widget runs from one of two hosts depending on environment:
EnvironmentHost
Sandboxhttps://kyc-widget.enterprise.sandbox.uphold.com
Productionhttps://kyc-widget.enterprise.uphold.com

Setup

1. Install the SDK

Install the SDK in the frontend that will host the Widget — your web app, or the JS bundle loaded by your native WebView.
npm install @uphold/enterprise-kyc-widget-web-sdk

2. Allow the Widget domain in your CSP

The Widget loads in an iframe. If your app uses a Content Security Policy, allow the Widget host for your environment(s) under frame-src.
<meta
  http-equiv="Content-Security-Policy"
  content="frame-src 'self' https://kyc-widget.enterprise.sandbox.uphold.com https://kyc-widget.enterprise.uphold.com;"
>
If your app does not use CSP, skip this step.

3. Create a session on your backend

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:
curl -X POST https://api.sandbox.uphold.com/widgets/kyc/sessions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: user $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{ "flow": "verify", "processes": ["identity", "proof-of-address"] }'
The response wraps the session object:
{
  "session": {
    "flow": "verify",
    "data": {
      "processes": ["identity", "proof-of-address"]
    },
    "url": "https://kyc-widget.enterprise.sandbox.uphold.com/...",
    "token": "..."
  }
}
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.

4. Initialize and mount the Widget

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 3
const 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.

5. Handle Widget events

The Widget emits four events during its lifecycle. Wire up handlers before calling mountIframe.
EventFires whenWhat to do
readyThe Widget has finished loadingHide your loading state
completeThe user submitted all KYC processesCall widget.unmount(), then monitor outcomes via KYC webhooks
cancelThe user dismissed the WidgetCall widget.unmount(), return them to your flow
errorThe Widget hit an unrecoverable errorRead event.detail.error, call widget.unmount(), retry
The Widget does not unmount itself. You must call widget.unmount() from complete, cancel, and error handlers.
widget.on('ready', () => {
  console.log('KYC Widget is ready');
});

widget.on('complete', () => {
  console.log('KYC processes submitted');
  widget.unmount();
});

widget.on('cancel', () => {
  console.log('KYC cancelled');
  widget.unmount();
});

widget.on('error', (event) => {
  console.error('KYC error:', event.detail.error);
  widget.unmount();
});
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.

6. Test in Sandbox

With your Sandbox credentials and the Sandbox Widget host configured, run through this checklist:
  1. The Widget mounts and ready fires.
  2. Completing the verification flow fires complete.
  3. Closing or dismissing the Widget fires cancel.
  4. 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 app integration

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.

WebView HTML template

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.

Platform setup

import WebKit

class KycViewController: UIViewController, WKScriptMessageHandler {
  @IBOutlet weak var webView: WKWebView!

  override func viewDidLoad() {
    super.viewDidLoad()

    // Register a single message handler for all Widget events
    let contentController = webView.configuration.userContentController
    contentController.add(self, name: "kycWidgetMessage")

    if let url = Bundle.main.url(forResource: "kyc-widget", withExtension: "html") {
      webView.loadFileURL(url, allowingReadAccessTo: url.deletingLastPathComponent())
    }
  }

  func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
    guard message.name == "kycWidgetMessage",
          let messageDict = message.body as? [String: Any],
          let type = messageDict["type"] as? String else {
      return
    }

    switch type {
      case "complete": handleKycComplete()
      case "cancel":   handleKycCancel()
      case "error":    handleKycError(error: messageDict["data"])
      default: print("Unknown KYC Widget message type: \(type)")
    }
  }

  private func handleKycComplete() { /* navigate to success */ }
  private func handleKycCancel() { /* return user to previous screen */ }
  private func handleKycError(error: Any?) { /* show error UI */ }

  deinit {
    webView?.configuration.userContentController.removeScriptMessageHandler(forName: "kycWidgetMessage")
  }
}

Configuration reference

The most common SDK options. See the SDK reference for the full schema and all event types.
OptionPurpose
themeCustomize the Widget’s appearance: force light or dark mode, set brand colors, typography, and per-component border radii. See KycTheme for all options.
debugVerbose console logging. Use during development.

Troubleshooting

Widget not displaying Confirm 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 mount The iframe fills its container — the container must have explicit CSS width and height. Minimum recommended size is 400px × 600px. Events not firing in native apps Verify 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).

Next steps

  • Review the complete SDK Reference for all available methods and events.
  • Follow the user onboarding guide for a step-by-step walkthrough of verifying users with the KYC Widget.