Veris Capture

Veris Capture runs entirely on-device. When a user completes a capture session, the SDK returns a signed result (signedResult) that carries a hash of the captured image along with quality and liveness scores. Your backend sends this result to Veris to be verified, and decides whether to proceed - all without Veris ever seeing the actual face image.

The SDK handles:

• Quality gate - 12 checks including lighting, blur, occlusion, and face positioning
• Human face validation - confirms the image contains a real human face
• Passive liveness (LBP) - detects spoofing from printed photos and screens (Launch, Scale, and Pro)
• Active liveness challenges - requires the user to perform specific facial actions (Scale: 1 random; Pro: 2–4 configurable)
• Video capture - records the full session as a video (Pro only)

Pick your platform below. The integration follows the same three-step pattern across all platforms: install the dependency, init once at startup, start a capture session when you need one.

dependencies {
    implementation 'com.verisinfra:veris-capture-android:1.3.0'
}

class MainActivity : AppCompatActivity() {

    // Declare as a field - must be registered before onStart
    val verisLauncher = VerisCapture.registerForResult(this) { result ->
        when (result) {
            is VerisResult.Success              -> verifyWithBackend(result)
            is VerisResult.Failure              -> showError(result.humanReadableReason)
            is VerisResult.Cancelled            -> { /* user dismissed */ }
            is VerisResult.SubscriptionInactive -> showUpgradePrompt()
        }
    }
}

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    VerisCapture.init(
        context  = this,
        config   = VerisConfig(
            licenseKey = "veris_sandbox_reg_xxxx",
            initNonce  = fetchNonceFromBackend(),
        ),
    ) { initResult ->
        if (initResult is VerisInitResult.Ready) {
            // SDK ready - initResult.licenseInfo.featureSummary available
        }
    }
}

VerisCapture.startCapture(
    launcher = verisLauncher,
    config   = VerisSessionConfig(nonce = fetchNonceFromBackend()),
)

// 3 active liveness rounds (Pro only, 2–4)
VerisSessionConfig(
    nonce                   = fetchNonceFromBackend(),
    proRandomChallengeCount = 3,
)

// Always require active liveness, even if passive already passed (Pro only)
VerisSessionConfig(
    nonce            = fetchNonceFromBackend(),
    enforceChallenge = true,
)

pod 'VerisCapture', '~> 1.3'

VerisCapture.initialise(
    config: VerisConfig(
        licenseKey: "veris_sandbox_xxxx",
        initNonce: nonceFromBackend
    )
) { result in
    if case .ready = result { /* SDK ready */ }
}

VerisCapture.startVerification(
    from: self,
    session: VerisSessionConfig(nonce: nonceFromBackend)
) { [weak self] result in
    switch result {
    case .success(let capture):
        self?.verifyWithBackend(capture.signedResult)
    case .failure(_, let reason, let retryable):
        self?.showError(reason, canRetry: retryable)
    case .cancelled:
        break
    case .subscriptionInactive:
        self?.showUpgradePrompt()
    case .error(_, let message):
        self?.showError(message, canRetry: true)
    }
}

// 3 active liveness rounds (Pro only, 2–4)
VerisSessionConfig(nonce: nonceFromBackend, proRandomChallengeCount: 3)

// Always require active liveness, even if passive already passed (Pro only)
VerisSessionConfig(nonce: nonceFromBackend, enforceChallenge: true)

dependencies:
  veris_capture: ^1.3.0

await VerisCapture.instance.initialise(
  config: VerisConfig(
    licenseKey: 'veris_sandbox_xxxx',
    initNonce: await fetchNonceFromBackend(),
  ),
);

final result = await VerisCapture.instance.startVerification(
  session: VerisSessionConfig(nonce: await fetchNonceFromBackend()),
);

switch (result) {
  case VerisSuccess s:
    verifyWithBackend(s.signedResult);
  case VerisFailure f:
    showError(f.humanReadableReason);
  case VerisCancelled _:
    break;
  case VerisSubscriptionInactive _:
    showUpgradePrompt();
  case VerisError e:
    showError(e.message);
}

// 3 active liveness rounds (Pro only, 2–4)
final result = await VerisCapture.instance.startVerification(
  session: VerisSessionConfig(
    nonce: await fetchNonceFromBackend(),
    proRandomChallengeCount: 3,
  ),
);

// Always require active liveness, even if passive already passed (Pro only)
final result = await VerisCapture.instance.startVerification(
  session: VerisSessionConfig(
    nonce: await fetchNonceFromBackend(),
    enforceChallenge: true,
  ),
);

npm install @verisinfra/react-native-capture

# iOS - install native pods
cd ios && pod install

import { VerisCapture } from '@verisinfra/react-native-capture';

await VerisCapture.initialise({
  licenseKey: 'veris_sandbox_xxxx',
  initNonce: await fetchNonceFromBackend(),
});

const result = await VerisCapture.startVerification({
  nonce: await fetchNonceFromBackend(),
});

switch (result.type) {
  case 'success':
    verifyWithBackend(result.signedResult);
    break;
  case 'failure':
    Alert.alert('Verification failed', result.reason);
    break;
  case 'cancelled':
    break;
  case 'subscriptionInactive':
    showUpgradePrompt();
    break;
  case 'error':
    Alert.alert('Something went wrong', result.message);
    break;
}

// 3 active liveness rounds (Pro only, 2–4)
const result = await VerisCapture.startVerification({
  nonce: await fetchNonceFromBackend(),
  proRandomChallengeCount: 3,
});

// Always require active liveness, even if passive already passed (Pro only)
const result = await VerisCapture.startVerification({
  nonce: await fetchNonceFromBackend(),
  enforceChallenge: true,
});

The SDK always ends a session with a typed result - it never throws an unhandled exception or silently fails. The four outcomes below are the ones to handle. The iOS, Flutter and React Native wrappers also report an error result for unexpected problems; treat it as retryable.

On a successful capture, the SDK returns signedResult: a compact signed token (a JWS signed with ES256 by a key held in the device's secure hardware). It has three dot-separated parts, and the middle part is the JSON below. Send the token to your backend as-is; do not modify it. Do not make decisions from a decoded copy on the phone. Your backend verifies it with Veris (next section).

{
  "ver": "2.0",
  "status": "SUCCESS",
  "session_id": "uuid-v4",
  "nonce": "uuid-v4-from-your-backend",
  "timestamp": "2026-03-01T12:00:00Z",
  "environment": "production",
  "plan": "scale",
  "sdk_version": "1.3.0",
  "platform": "android",
  "package_name": "com.example.app",
  "quality_score": 0.87,
  "liveness_score": 0.82,
  "face_hash": "sha256-of-captured-image",
  "hardware_backed": true,
  "validation_state": "verified",
  "injection_risk": 0.0,
  "challenges_completed": ["head_turn", "blink"]
}

After receiving signedResult from the SDK, your mobile app passes it to your backend, which then calls Veris to verify it. A successful response confirms the signature is genuine, the nonce has not been replayed, and the session belongs to your license. Once it is verified, you can read the scores from the token's payload.

Request

{
  "license_key": "veris_live_xxxx",
  "token": "<the signedResult string from the SDK>"
}

Older SDKs that return a separate payload and signature can send signed_payload and signature instead of token.

Response - verified (HTTP 200)

{
  "ok": true,
  "valid": true,
  "environment": "production",
  "nonce_status": "fresh",
  "plan": "scale",
  "verified_at": "2026-03-01T12:00:03Z"
}

Response - rejected

A rejected result comes back with a non-200 status, valid: false, and the reason in reason (also in error).

// HTTP 422 (other statuses below)
{
  "ok": false,
  "valid": false,
  "error": "NONCE_REPLAYED",
  "reason": "NONCE_REPLAYED",
  "message": "NONCE_REPLAYED"
}

Nonces prevent replay attacks - an attacker capturing a valid signed result cannot reuse it. Here's the full flow:

1. Your backend generates a UUID v4 nonce for each session and stores it with a short TTL.
2. Your mobile app passes the nonce when it starts a session (startCapture on Android, startVerification on iOS, Flutter and React Native).
3. The SDK includes the nonce in its validation call to Veris. Veris holds it for 10 minutes.
4. The SDK embeds the nonce in the signed result.
5. Your mobile app sends signedResult to your backend.
6. Your backend calls POST /v1/sdk/verify-result. Veris checks the nonce hasn't been used before, marks it used, and returns a verified response.
7. Any attempt to reuse the same nonce is rejected with NONCE_REPLAYED.

Feature availability is controlled by your plan. The SDK reads the feature flags on each validation call and never needs a code change when you upgrade.

When you downgrade, the SDK reads the updated feature flags on its next validation call (max 1 hour delay). It never crashes on downgrade - features simply become unavailable and the liveness checks your plan no longer includes do not run.

Sandbox keys (veris_sandbox_*) let you build and test your integration without a paid subscription.

• 50 validations per day - hard cap, resets at midnight UTC. Exceeding this returns SANDBOX_LIMIT_REACHED.
• 10 Compare calls lifetime - total across all sandbox sessions. Returns SANDBOX_COMPARE_LIMIT_REACHED with an upgrade URL when exhausted.
• SANDBOX badge - the SDK shows a small amber "SANDBOX" badge in the top-right corner of the camera preview. It does not interfere with the face oval or liveness instructions. Completely removed when a production key is used.
• Environment flag - all results include "environment": "sandbox".
• Sandbox results rejected in production - POST /v1/sdk/verify-result rejects sandbox-signed results with SANDBOX_RESULT_REJECTED. You cannot mix environments.

These are published commitments about SDK behaviour. They hold across all plan levels and all platforms.

• Never throws an unhandled exception into the host app. All errors are returned as typed result states.
• Always returns a final state. Every session ends with Success, Failure, Cancelled, or SubscriptionInactive - never silent failure.
• Never silently retries indefinitely. If a validation call fails, the SDK surfaces the error rather than looping.
• Releases all camera, CPU, and memory on completion, backgrounding, or dismiss. The SDK does not hold resources after the session ends.
• Adds about 20 MB per device architecture. Ship an App Bundle (or per-ABI splits) so each device downloads only its own architecture. Includes the on-device face detector and anti-spoof model - no server round trips during capture.
• Does not access the camera in the background under any circumstances. Camera access begins when startCapture is called and ends when the session result is returned.