KYC Widget installation and setup

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:

Environment	Host
Sandbox	`https://kyc-widget.enterprise.sandbox.uphold.com`
Production	`https://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

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", "profile", "proof-of-address"] }'

The response wraps the session object:

{
  "session": {
    "flow": "verify",
    "data": {
      "processes": ["identity", "profile", "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. 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.

The Widget emits four events during its lifecycle. Wire up handlers before calling mountIframe.

Event	Fires when	What to do
`ready`	The Widget has finished loading	Hide your loading state
`complete`	The user submitted all KYC processes	Call `widget.unmount()`, then monitor outcomes via KYC webhooks
`cancel`	The user dismissed the Widget	Call `widget.unmount()`, return them to your flow
`error`	The Widget hit an unrecoverable error	Read `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:

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 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

iOS (Swift)
Android (Java/Kotlin)
React Native

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")
  }
}

import android.webkit.WebView;
import android.webkit.WebSettings;
import android.webkit.JavascriptInterface;
import android.util.Log;
import org.json.JSONObject;

WebView webView = findViewById(R.id.webview);
WebSettings webSettings = webView.getSettings();
webSettings.setJavaScriptEnabled(true);

webView.addJavascriptInterface(new KycBridge(), "KycBridge");
webView.loadUrl("file:///android_asset/kyc-widget.html");

public class KycBridge {
  @JavascriptInterface
  public void onMessage(String messageJson) {
    try {
      JSONObject message = new JSONObject(messageJson);
      String type = message.getString("type");
      Object data = message.opt("data");

      runOnUiThread(() -> {
        switch (type) {
          case "complete": handleKycComplete(); break;
          case "cancel":   handleKycCancel(); break;
          case "error":    handleKycError(data != null ? data.toString() : null); break;
          default: Log.w("Kyc", "Unknown KYC Widget message type: " + type);
        }
      });
    } catch (Exception e) {
      Log.e("Kyc", "Error parsing KYC Widget message", e);
    }
  }

  private void handleKycComplete() { /* navigate to success */ }
  private void handleKycCancel() { /* return user to previous screen */ }
  private void handleKycError(String error) { /* show error UI */ }
}

If you load local assets, ensure the WebView allows file access according to your security requirements (e.g. setAllowFileAccess(true) when needed).

import { WebView } from 'react-native-webview';
import { Alert } from 'react-native';

const KycScreen = () => {
  const handleMessage = (event) => {
    try {
      const message = JSON.parse(event.nativeEvent.data);

      switch (message.type) {
        case 'complete': handleKycComplete(); break;
        case 'cancel':   handleKycCancel(); break;
        case 'error':    handleKycError(message.data); break;
        default: console.log('Unknown message type:', message.type);
      }
    } catch (error) {
      console.error('Error parsing WebView message:', error);
    }
  };

  const handleKycComplete = () => { /* navigate to success */ };
  const handleKycCancel = () => { /* return user to previous screen */ };
  const handleKycError = (error) => { /* show error UI */ };

  return (
    <WebView
      source={{ uri: 'file:///path/to/kyc-widget.html' }}
      javaScriptEnabled={true}
      domStorageEnabled={true}
      onMessage={handleMessage}
    />
  );
};

For iOS, file:// URLs may be restricted. Consider source={{ html: '<html>...</html>' }} or a bundled asset, adjusted per platform.

Configuration reference

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 WidgetThemeOption for all options.
`debug`	Verbose 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.

Payment Widget

Travel Rule Widget

KYC Widget

Topper

KYC Widget installation and setup

Before you start

Setup

1. Install the SDK

2. Allow the Widget domain in your CSP

3. Create a session on your backend

4. Initialize and mount the Widget

5. Handle Widget events

6. Test in Sandbox

Native app integration

WebView HTML template

Platform setup

Configuration reference

Troubleshooting

Next steps

​Before you start

​Setup

​1. Install the SDK

​2. Allow the Widget domain in your CSP

​3. Create a session on your backend

​4. Initialize and mount the Widget

​5. Handle Widget events

​6. Test in Sandbox

​Native app integration

​WebView HTML template

​Platform setup

​Configuration reference

​Troubleshooting

​Next steps

Before you start

Setup

1. Install the SDK

2. Allow the Widget domain in your CSP

3. Create a session on your backend

4. Initialize and mount the Widget

5. Handle Widget events

6. Test in Sandbox

Native app integration

WebView HTML template

Platform setup

Configuration reference

Troubleshooting

Next steps