Web SDK

Overview

Instead of redirecting users to pawaPass, you can embed the verification flow directly in your application using the Web SDK. The SDK creates and manages a secure iframe, handles communication via postMessage, and delivers results through callbacks. No cookies, no redirects, no sensitive data in your frontend.

Redirect (default)

User leaves your site, completes verification on pawaPass, returns via successUrl / errorUrl.

Iframe SDK

User stays on your site. Verification runs inside a managed iframe. You control the surrounding UX.

Try the live demo to see the SDK in action before integrating.

Installation

<script src="https://cdn.pawapass.com/web-sdk/latest/pawapass.min.js"></script>

npm install @pawapass/web-sdk

pnpm add @pawapass/web-sdk

The CDN version exposes a global PawaPass object. The npm package provides a default ES module export. Zero runtime dependencies.

npm registry configuration

The @pawapass scope is hosted on a separate registry. To install the package with npm or pnpm, tell your package manager where to find the scope by adding this line to your .npmrc (in the project root, or ~/.npmrc for all projects):

.npmrc

@pawapass:registry=https://europe-npm.pkg.dev/pawapass-overlord/pawapass-npm/

With that entry in place, npm install @pawapass/web-sdk and pnpm add @pawapass/web-sdk resolve the package normally. The CDN needs no configuration.

We need to register every domain that runs the SDK before it will work. Verification will fail on domains we have not registered. Contact us with the domains you want to use.

Quick start

Create a verification (server-side)

Your backend creates a verification and passes the returned id (used as verificationId in the SDK) to the frontend. This keeps your API key on the server.

Add a container element

<div id="pawapass-container"></div>

Initialize the SDK

<script src="https://cdn.pawapass.com/web-sdk/latest/pawapass.min.js"></script>
<script>
  PawaPass.init({
    publicKey: 'pk_prod_xxx',
    verificationId: 'aB1cD2eF',
    containerId: 'pawapass-container',
    callbacks: {
      onReady() { console.log('SDK ready'); },
      onComplete(result) { console.log('Done:', result.status); },
      onError(error) { console.error('SDK error:', error.code); },
      onCancel() { console.log('User cancelled'); },
    },
  });
</script>

import PawaPass from '@pawapass/web-sdk';

PawaPass.init({
  publicKey: 'pk_prod_xxx',
  verificationId: 'aB1cD2eF',
  containerId: 'pawapass-container',
  callbacks: {
    onReady() { console.log('SDK ready'); },
    onComplete(result) { console.log('Done:', result.status); },
    onError(error) { console.error('SDK error:', error.code); },
    onCancel() { console.log('User cancelled'); },
  },
});

Configuration

string

required

Your public key for client identification. Safe to expose in frontend code. This is not your API key.The key format is pk_{env}_{key} (e.g. pk_prod_abc123). The SDK automatically resolves the correct pawaPass environment from the key prefix, so no separate environment or URL configuration is needed.Contact us to obtain your public key.

string

required

Verification ID obtained from your backend via the Create verification endpoint.

string

required

ID of the HTML element where the iframe will be mounted.

object

required

Object with callback functions. See Callbacks below.

string

default:"en"

UI language. Supported: en, rw, sw, pt, fr.

boolean

default:"false"

When true, stores a device identifier in localStorage for consistent analytics identity across sessions. When false (default), the device ID is stored in memory only and cleared on destroy().

Callbacks

onReady

Fired when the iframe is loaded and ready. Use to show a “Start verification” button or hide loading spinners.

onStart (optional)

Fired when the user begins the verification process. Use for analytics or logging.

onComplete

Fired when the verification process finishes.

Example result

{
  "verificationId": "aB1cD2eF",
  "status": "APPROVED"
}

Status	Meaning
`APPROVED`	Verification successful
`DECLINED`	Verification rejected
`REVIEW`	Waiting for manual agent review
`USER_DATA_COLLECTED`	User data submitted, processing verification

REVIEW and USER_DATA_COLLECTED are not final statuses. The final result will arrive via webhook. No further user action is needed. The client-side flow is complete.

onError

Fired on SDK-level errors. Verification errors (e.g. blurry document) are handled inside the iframe and do not trigger this callback.

Error code	Description
`IFRAME_LOAD_FAILED`	Iframe failed to load
`IFRAME_READY_TIMEOUT`	Iframe did not respond within 15 seconds
`NETWORK_ERROR`	Connection to pawaPass failed
`INVALID_PUBLIC_KEY`	Public key not recognized
`INVALID_CONFIG`	Invalid SDK configuration
`CONTAINER_NOT_FOUND`	Container element not found in DOM
`ORIGIN_NOT_ALLOWED`	Parent origin is not allowed for this partner
`FULLSCREEN_NOT_SUPPORTED`	Browser does not support fullscreen mode for iframes

Safe to retry init() with the same verificationId. No need to create a new session.

onCancel

Fired when the user exits verification by clicking the “back” button.

In a future release, onCancel will include context about at which step the user decided to abandon the verification process.

Cleanup

init() returns an instance. Keep the reference and call destroy() on it to remove the iframe and clean up all event listeners and timers:

const pawapass = PawaPass.init({
  // ...config
});

// later, when you need to tear down:
pawapass.destroy();

Important for SPAs where the user may navigate away mid-verification. Calling init() again on the same container automatically destroys the previous instance.

Architecture

Content Security Policy

The SDK makes one request from the parent page to validate the public key and fetch partner configuration. The iframe handles all other network requests. If your site uses a Content Security Policy, add the following directives:

Directive	Value	Why
`script-src`	`https://cdn.pawapass.com`	Loading the SDK via script tag
`frame-src`	depends on key prefix	Verification iframe
`connect-src`	depends on key prefix	Public key validation request

The frame-src and connect-src domains are determined by your public key prefix:

Key prefix	Domain
`pk_prod_`	`https://app.pawapass.com`
`pk_{env}_` (e.g. `pk_sandbox1_`)	`https://app.{env}.pawapass.com`

Browser support

The SDK targets ES5+ and supports all modern browsers. Users on unsupported browsers (including Opera Mini Presto/Extreme mode) will see a fallback message inside the iframe.

Full example

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>pawaPass Verification</title>
  </head>
  <body>
    <div id="pawapass-container"></div>

    <script src="https://cdn.pawapass.com/web-sdk/latest/pawapass.min.js"></script>
    <script>
      // verificationId should come from your backend
      const verificationId = 'aB1cD2eF';

      PawaPass.init({
        publicKey: 'pk_prod_xxx',
        verificationId,
        containerId: 'pawapass-container',
        language: 'en',
        callbacks: {
          onReady() {
            console.log('Iframe loaded and ready');
          },
          onStart() {
            console.log('User started verification');
          },
          onComplete(result) {
            console.log('Verification complete:', result.status);
            // result: { verificationId, status }
          },
          onError(error) {
            console.error('SDK error:', error.code, error.message);
          },
          onCancel() {
            console.log('User cancelled');
          },
        },
      });
    </script>
  </body>
</html>

import PawaPass from '@pawapass/web-sdk';

// verificationId should come from your backend
const verificationId = 'aB1cD2eF';

PawaPass.init({
  publicKey: 'pk_prod_xxx',
  verificationId,
  containerId: 'pawapass-container',
  language: 'en',
  callbacks: {
    onReady() {
      console.log('Iframe loaded and ready');
    },
    onStart() {
      console.log('User started verification');
    },
    onComplete(result) {
      console.log('Verification complete:', result.status);
      // result: { verificationId, status }
    },
    onError(error) {
      console.error('SDK error:', error.code, error.message);
    },
    onCancel() {
      console.log('User cancelled');
    },
  },
});

Get Started

Guides

Overview

Redirect (default)

Iframe SDK

Installation

npm registry configuration

Quick start

Configuration

Callbacks

onReady

onStart (optional)

onComplete

onError

onCancel

Cleanup

Architecture

Content Security Policy

Browser support

Full example

​Overview

Redirect (default)

Iframe SDK

​Installation

​npm registry configuration

​Quick start

​Configuration

​Callbacks

​onReady

​onStart (optional)

​onComplete

​onError

​onCancel

​Cleanup

​Architecture

​Content Security Policy

​Browser support

​Full example

Overview

Installation

npm registry configuration

Quick start

Configuration

Callbacks

onReady

onStart (optional)

onComplete

onError

onCancel

Cleanup

Architecture

Content Security Policy

Browser support

Full example