Skip to main content

​
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>
The CDN version exposes a global PawaPass object. The npm package provides a default ES module export. Zero runtime dependencies.
Every domain that runs the SDK must be whitelisted. The SDK will load and initialize on any domain, but the FaceTec liveness check will fail if the domain is not on the allowlist. This applies to all environments, including localhost. Contact us to register your domains.

​
Quick start

1

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

Add a container element

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

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>

​
Configuration

​
publicKey
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.
​
verificationId
string
required
Verification ID obtained from your backend via the Create verification endpoint.
​
containerId
string
required
ID of the HTML element where the iframe will be mounted.
​
callbacks
object
required
Object with callback functions. See Callbacks below.
​
language
string
default:"en"
UI language. Supported: en, rw, sw, pt, fr.
​
persistDeviceId
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"
}
StatusMeaning
APPROVEDVerification successful
DECLINEDVerification rejected
REVIEWWaiting for manual agent review
USER_DATA_COLLECTEDUser 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 codeDescription
IFRAME_LOAD_FAILEDIframe failed to load
IFRAME_READY_TIMEOUTIframe did not respond within 15 seconds
NETWORK_ERRORConnection to pawaPass failed
INVALID_PUBLIC_KEYPublic key not recognized
INVALID_CONFIGInvalid SDK configuration
CONTAINER_NOT_FOUNDContainer element not found in DOM
ORIGIN_NOT_ALLOWEDParent origin is not allowed for this partner
FULLSCREEN_NOT_SUPPORTEDBrowser 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

Call destroy() to remove the iframe and clean up all event listeners and timers: 
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:
DirectiveValueWhy
script-srchttps://cdn.pawapass.comLoading the SDK via script tag
frame-srcdepends on key prefixVerification iframe
connect-srcdepends on key prefixPublic key validation request
The frame-src and connect-src domains are determined by your public key prefix:
Key prefixDomain
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>