Integration guide

curl -X POST "https://kyc.example.com/v1/onboarding-requests" \
  -H "Authorization: Bearer $VERIFYME_API_KEY" \
  -H "Idempotency-Key: kyc-user-8841-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "externalReference": "USER-8841",
    "applicantType": "merchant",
    "mobile": "9876541234",
    "email": "ravi@example.com",
    "flowKey": "india-business-kyc-v1",
    "returnUrl": "https://shop.example.com/kyc/done",
    "expiresInHours": 72,
    "locale": "en",
    "metadata": { "plan": "gold" }
  }'
# Then send the user to the onboardingUrl from the response (HTTP 303 redirect).

// Express 4/5, Node 18+ (global fetch)
import express from "express";

const app = express();
const HOST = process.env.VERIFYME_HOST;          // https://kyc.example.com
const KEY = process.env.VERIFYME_API_KEY;        // vm_test_... or vm_live_...

app.post("/kyc/start", requireLogin, async (req, res) => {
  const user = req.user;
  const r = await fetch(`${HOST}/v1/onboarding-requests`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
      // Stable per user action: a double click or a retry reuses the same request.
      "Idempotency-Key": `kyc-${user.id}-attempt-${user.kycAttempt}`,
    },
    body: JSON.stringify({
      externalReference: String(user.id),
      mobile: user.mobile,
      returnUrl: "https://shop.example.com/kyc/done",
    }),
  });
  if (!r.ok) {
    const { error } = await r.json();
    console.error("VerifyMe create failed", r.status, error.code, error.traceId);
    return res.status(502).send("Could not start verification. Please try again.");
  }
  const { requestId, onboardingUrl } = await r.json();
  await db.kycRequests.insert({ userId: user.id, requestId, status: "LINK_ISSUED" });
  res.redirect(303, onboardingUrl);
});

# Flask 3, requests
import os
import requests
from flask import Flask, redirect, abort, g

app = Flask(__name__)
HOST = os.environ["VERIFYME_HOST"]
KEY = os.environ["VERIFYME_API_KEY"]

@app.post("/kyc/start")
@login_required
def kyc_start():
    user = g.user
    r = requests.post(
        f"{HOST}/v1/onboarding-requests",
        headers={
            "Authorization": f"Bearer {KEY}",
            "Idempotency-Key": f"kyc-{user.id}-attempt-{user.kyc_attempt}",
        },
        json={
            "externalReference": str(user.id),
            "mobile": user.mobile,
            "returnUrl": "https://shop.example.com/kyc/done",
        },
        timeout=15,
    )
    if not r.ok:
        err = r.json().get("error", {})
        app.logger.error("VerifyMe create failed %s %s %s", r.status_code, err.get("code"), err.get("traceId"))
        abort(502)
    body = r.json()
    save_kyc_request(user.id, body["requestId"])
    return redirect(body["onboardingUrl"], code=303)

// ASP.NET Core 8 minimal API
using System.Net.Http.Json;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient("verifyme", c =>
{
    c.BaseAddress = new Uri(builder.Configuration["VerifyMe:Host"]!);      // https://kyc.example.com
    c.DefaultRequestHeaders.Authorization =
        new("Bearer", builder.Configuration["VerifyMe:ApiKey"]);
    c.Timeout = TimeSpan.FromSeconds(15);
});
var app = builder.Build();

app.MapPost("/kyc/start", async (IHttpClientFactory factory, HttpContext ctx) =>
{
    var userId = ctx.User.FindFirst("sub")!.Value;
    var http = factory.CreateClient("verifyme");

    var req = new HttpRequestMessage(HttpMethod.Post, "/v1/onboarding-requests")
    {
        Content = JsonContent.Create(new
        {
            externalReference = userId,
            mobile = "9876541234",
            returnUrl = "https://shop.example.com/kyc/done",
        }),
    };
    req.Headers.Add("Idempotency-Key", $"kyc-{userId}-attempt-1");

    var res = await http.SendAsync(req);
    if (!res.IsSuccessStatusCode) return Results.StatusCode(502);

    var created = await res.Content.ReadFromJsonAsync<CreatedRequest>();
    // persist created!.RequestId against the user here
    return Results.Redirect(created!.OnboardingUrl);                      // 302
});

app.Run();

record CreatedRequest(string RequestId, string OnboardingUrl, string Status, DateTime ExpiresAt);

// Spring Boot 3, Java 17 (java.net.http + Jackson)
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.view.RedirectView;

@RestController
public class KycController {
  private final HttpClient http = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
  private final ObjectMapper json = new ObjectMapper();
  @Value("${verifyme.host}") String host;
  @Value("${verifyme.api-key}") String apiKey;

  @PostMapping("/kyc/start")
  public RedirectView start() throws Exception {
    String userId = "8841";
    String body = json.writeValueAsString(java.util.Map.of(
        "externalReference", userId,
        "mobile", "9876541234",
        "returnUrl", "https://shop.example.com/kyc/done"));
    HttpRequest req = HttpRequest.newBuilder(URI.create(host + "/v1/onboarding-requests"))
        .timeout(Duration.ofSeconds(15))
        .header("Authorization", "Bearer " + apiKey)
        .header("Idempotency-Key", "kyc-" + userId + "-attempt-1")
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();
    HttpResponse<String> res = http.send(req, HttpResponse.BodyHandlers.ofString());
    if (res.statusCode() != 201) throw new ResponseStatusException(HttpStatus.BAD_GATEWAY);
    JsonNode created = json.readTree(res.body());
    // persist created.get("requestId").asText() against the user here
    RedirectView redirect = new RedirectView(created.get("onboardingUrl").asText());
    redirect.setStatusCode(HttpStatus.SEE_OTHER);
    return redirect;
  }
}

<?php
// Plain PHP 8 with the curl extension (works in Laravel/Symfony controllers too)
function createVerifyMeRequest(string $userId): array {
    $ch = curl_init(getenv('VERIFYME_HOST') . '/v1/onboarding-requests');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('VERIFYME_API_KEY'),
            'Idempotency-Key: kyc-' . $userId . '-attempt-1',
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'externalReference' => $userId,
            'mobile' => '9876541234',
            'returnUrl' => 'https://shop.example.com/kyc/done',
        ]),
    ]);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($code !== 201) {
        error_log("VerifyMe create failed: HTTP $code $body");
        http_response_code(502);
        exit('Could not start verification.');
    }
    return json_decode($body, true);
}

$created = createVerifyMeRequest($currentUser->id);
// persist $created['requestId'] against the user here
header('Location: ' . $created['onboardingUrl'], true, 303);
exit;

app.get("/kyc/done", requireLogin, async (req, res) => {
  const { requestId } = req.query;
  const record = await db.kycRequests.findOne({ requestId, userId: req.user.id });
  if (!record) return res.sendStatus(404);               // not this user's request
  // Do not trust ?status. The authoritative state arrives by webhook.
  res.render("kyc-pending", { state: record.status });
});

@app.get("/kyc/done")
@login_required
def kyc_done():
    request_id = request.args.get("requestId", "")
    record = find_kyc_request(user_id=g.user.id, request_id=request_id)
    if record is None:
        abort(404)
    # Do not trust ?status. The authoritative state arrives by webhook.
    return render_template("kyc_pending.html", state=record.status)

app.MapGet("/kyc/done", async (string requestId, HttpContext ctx, KycStore store) =>
{
    var record = await store.FindAsync(ctx.User.FindFirst("sub")!.Value, requestId);
    if (record is null) return Results.NotFound();
    // Do not trust ?status. The authoritative state arrives by webhook.
    return Results.Content($"Verification {record.Status}. We will notify you shortly.", "text/plain");
});

<?php
$requestId = $_GET['requestId'] ?? '';
$record = findKycRequest($currentUser->id, $requestId);
if (!$record) { http_response_code(404); exit; }
// Do not trust $_GET['status']. The authoritative state arrives by webhook.
echo 'Verification ' . htmlspecialchars($record['status']) . '. We will notify you shortly.';

curl -s "https://kyc.example.com/v1/onboarding-requests/vm_req_01M3TRSBZTTWMHGGTTGP/result" \
  -H "Authorization: Bearer $VERIFYME_API_KEY"

async function fetchResult(requestId) {
  const r = await fetch(`${HOST}/v1/onboarding-requests/${requestId}/result`, {
    headers: { Authorization: `Bearer ${KEY}` },
  });
  if (r.status === 409) return null;              // RESULT_NOT_READY: applicant has not submitted yet
  if (!r.ok) throw new Error(`VerifyMe ${r.status}`);
  const result = await r.json();
  if (result.status === "APPROVED") await markVerified(result.externalReference);
  if (result.status === "REJECTED") await markRejected(result.externalReference, result.decision.reasonCode);
  return result;
}

def fetch_result(request_id):
    r = requests.get(
        f"{HOST}/v1/onboarding-requests/{request_id}/result",
        headers={"Authorization": f"Bearer {KEY}"},
        timeout=15,
    )
    if r.status_code == 409:            # RESULT_NOT_READY
        return None
    r.raise_for_status()
    result = r.json()
    if result["status"] == "APPROVED":
        mark_verified(result["externalReference"])
    elif result["status"] == "REJECTED":
        mark_rejected(result["externalReference"], result["decision"]["reasonCode"])
    return result

async Task<JsonDocument?> FetchResultAsync(HttpClient http, string requestId)
{
    var res = await http.GetAsync($"/v1/onboarding-requests/{requestId}/result");
    if (res.StatusCode == HttpStatusCode.Conflict) return null;           // RESULT_NOT_READY
    res.EnsureSuccessStatusCode();
    return await JsonDocument.ParseAsync(await res.Content.ReadAsStreamAsync());
}

JsonNode fetchResult(String requestId) throws Exception {
  HttpRequest req = HttpRequest.newBuilder(URI.create(host + "/v1/onboarding-requests/" + requestId + "/result"))
      .header("Authorization", "Bearer " + apiKey).GET().build();
  HttpResponse<String> res = http.send(req, HttpResponse.BodyHandlers.ofString());
  if (res.statusCode() == 409) return null;            // RESULT_NOT_READY
  if (res.statusCode() != 200) throw new IllegalStateException("VerifyMe " + res.statusCode());
  return json.readTree(res.body());
}

<?php
function fetchResult(string $requestId): ?array {
    $ch = curl_init(getenv('VERIFYME_HOST') . "/v1/onboarding-requests/$requestId/result");
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('VERIFYME_API_KEY')]]);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($code === 409) return null;      // RESULT_NOT_READY
    if ($code !== 200) throw new RuntimeException("VerifyMe HTTP $code");
    return json_decode($body, true);
}

import { useEffect, useRef, useState } from "react";

export function VerifyButton({ startUrl = "/api/kyc/start" }) {
  const [state, setState] = useState("idle");
  const ready = useRef(false);

  useEffect(() => {
    if (ready.current || !window.VerifyMe) return;
    window.VerifyMe.init({
      publicKey: import.meta.env.VITE_VERIFYME_PUBLIC_KEY,
      onComplete: () => setState("submitted"),
      onClose: () => setState((s) => (s === "submitted" ? s : "idle")),
      onError: () => setState("error"),
    });
    ready.current = true;
    return () => window.VerifyMe.destroy();
  }, []);

  async function start() {
    setState("opening");
    const r = await fetch(startUrl, { method: "POST", credentials: "same-origin" });
    const { onboardingUrl } = await r.json();
    window.VerifyMe.open({ url: onboardingUrl, mode: "modal" });
  }

  if (state === "submitted") return <p role="status">Thanks. We are verifying your details.</p>;
  return <button onClick={start} disabled={state === "opening"}>Verify identity</button>;
}

<script setup>
import { onMounted, onBeforeUnmount, ref } from "vue";

const state = ref("idle");

onMounted(() => {
  window.VerifyMe.init({
    publicKey: import.meta.env.VITE_VERIFYME_PUBLIC_KEY,
    onComplete: () => (state.value = "submitted"),
    onError: () => (state.value = "error"),
  });
});
onBeforeUnmount(() => window.VerifyMe.destroy());

async function start() {
  const r = await fetch("/api/kyc/start", { method: "POST", credentials: "same-origin" });
  const { onboardingUrl } = await r.json();
  window.VerifyMe.open({ url: onboardingUrl, mode: "modal" });
}
</script>

<template>
  <p v-if="state === 'submitted'" role="status">Thanks. We are verifying your details.</p>
  <button v-else type="button" @click="start">Verify identity</button>
</template>

// kyc.component.ts (standalone component, Angular 17+)
import { Component, OnDestroy, OnInit, signal } from "@angular/core";
import { HttpClient } from "@angular/common/http";

declare const VerifyMe: any;   // loaded by <script src=".../sdk/v1/verifyme.js"> in index.html

@Component({
  selector: "app-kyc",
  standalone: true,
  template: `
    @if (submitted()) { <p role="status">Thanks. We are verifying your details.</p> }
    @else { <button type="button" (click)="start()">Verify identity</button> }
  `,
})
export class KycComponent implements OnInit, OnDestroy {
  submitted = signal(false);
  constructor(private http: HttpClient) {}

  ngOnInit() {
    VerifyMe.init({ publicKey: "vm_pk_test_xxxxxxxxxxxxxxxxxx", onComplete: () => this.submitted.set(true) });
  }
  ngOnDestroy() { VerifyMe.destroy(); }

  start() {
    this.http.post<{ onboardingUrl: string }>("/api/kyc/start", {}).subscribe(({ onboardingUrl }) =>
      VerifyMe.open({ url: onboardingUrl, mode: "modal" }));
  }
}

// AndroidManifest.xml
// <uses-permission android:name="android.permission.CAMERA" />
// <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
// <uses-permission android:name="android.permission.INTERNET" />

class KycActivity : AppCompatActivity() {
  private lateinit var web: WebView
  private var pendingPermission: PermissionRequest? = null
  private var pendingGeo: Pair<String, GeolocationPermissions.Callback>? = null
  private var filePathCallback: ValueCallback<Array<Uri>>? = null

  private val askPermissions =
    registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { granted ->
      pendingPermission?.let { if (granted[Manifest.permission.CAMERA] == true) it.grant(it.resources) else it.deny() }
      pendingGeo?.let { (origin, cb) -> cb.invoke(origin, granted[Manifest.permission.ACCESS_FINE_LOCATION] == true, false) }
      pendingPermission = null; pendingGeo = null
    }

  private val pickFile =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { r ->
      filePathCallback?.onReceiveValue(WebChromeClient.FileChooserParams.parseResult(r.resultCode, r.data))
      filePathCallback = null
    }

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    web = WebView(this).also { setContentView(it) }
    web.settings.javaScriptEnabled = true
    web.settings.domStorageEnabled = true
    web.settings.mediaPlaybackRequiresUserGesture = false

    web.webViewClient = object : WebViewClient() {
      override fun shouldOverrideUrlLoading(v: WebView, req: WebResourceRequest): Boolean {
        val uri = req.url
        if (uri.scheme == "myapp" && uri.host == "kyc") {            // returnUrl hand-off
          onKycReturned(uri.getQueryParameter("requestId"), uri.getQueryParameter("status"))
          finish(); return true
        }
        return false
      }
    }
    web.webChromeClient = object : WebChromeClient() {
      override fun onPermissionRequest(request: PermissionRequest) {
        pendingPermission = request
        askPermissions.launch(arrayOf(Manifest.permission.CAMERA))
      }
      override fun onGeolocationPermissionsShowPrompt(origin: String, cb: GeolocationPermissions.Callback) {
        pendingGeo = origin to cb
        askPermissions.launch(arrayOf(Manifest.permission.ACCESS_FINE_LOCATION))
      }
      override fun onShowFileChooser(v: WebView, cb: ValueCallback<Array<Uri>>, params: FileChooserParams): Boolean {
        filePathCallback?.onReceiveValue(null); filePathCallback = cb
        pickFile.launch(params.createIntent()); return true
      }
    }
    web.loadUrl(intent.getStringExtra("onboardingUrl")!!)
  }
}

// Info.plist: NSCameraUsageDescription, NSMicrophoneUsageDescription, NSLocationWhenInUseUsageDescription
import SwiftUI
import WebKit

struct KycWebView: UIViewRepresentable {
  let url: URL
  var onReturn: (String?, String?) -> Void

  func makeCoordinator() -> Coordinator { Coordinator(onReturn: onReturn) }

  func makeUIView(context: Context) -> WKWebView {
    let cfg = WKWebViewConfiguration()
    cfg.allowsInlineMediaPlayback = true
    cfg.mediaTypesRequiringUserActionForPlayback = []
    let web = WKWebView(frame: .zero, configuration: cfg)
    web.navigationDelegate = context.coordinator
    web.uiDelegate = context.coordinator
    web.load(URLRequest(url: url))
    return web
  }
  func updateUIView(_ web: WKWebView, context: Context) {}

  final class Coordinator: NSObject, WKNavigationDelegate, WKUIDelegate {
    let onReturn: (String?, String?) -> Void
    init(onReturn: @escaping (String?, String?) -> Void) { self.onReturn = onReturn }

    func webView(_ webView: WKWebView, decidePolicyFor action: WKNavigationAction,
                 decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
      if let u = action.request.url, u.scheme == "myapp", u.host == "kyc" {     // returnUrl hand-off
        let q = URLComponents(url: u, resolvingAgainstBaseURL: false)?.queryItems
        onReturn(q?.first { $0.name == "requestId" }?.value, q?.first { $0.name == "status" }?.value)
        decisionHandler(.cancel); return
      }
      decisionHandler(.allow)
    }

    // iOS 15+: the system prompt appears once per origin; grant so the web page can use the camera.
    @available(iOS 15.0, *)
    func webView(_ webView: WKWebView, requestMediaCapturePermissionFor origin: WKSecurityOrigin,
                 initiatedByFrame frame: WKFrameInfo, type: WKMediaCaptureType,
                 decisionHandler: @escaping (WKPermissionDecision) -> Void) {
      decisionHandler(.prompt)
    }
  }
}

import React from "react";
import { PermissionsAndroid, Platform } from "react-native";
import { WebView } from "react-native-webview";

async function ensureAndroidPermissions() {
  if (Platform.OS !== "android") return;
  await PermissionsAndroid.requestMultiple([
    PermissionsAndroid.PERMISSIONS.CAMERA,
    PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
  ]);
}

export function KycScreen({ route, navigation }) {
  const { onboardingUrl } = route.params;
  React.useEffect(() => { ensureAndroidPermissions(); }, []);

  return (
    <WebView
      source={{ uri: onboardingUrl }}
      javaScriptEnabled
      domStorageEnabled
      allowsInlineMediaPlayback
      mediaPlaybackRequiresUserAction={false}
      geolocationEnabled
      onShouldStartLoadWithRequest={(req) => {
        if (req.url.startsWith("myapp://kyc/")) {          // returnUrl hand-off
          const q = new URL(req.url).searchParams;
          navigation.replace("KycPending", { requestId: q.get("requestId") });
          return false;
        }
        return true;
      }}
    />
  );
}
// iOS: add NSCameraUsageDescription and NSLocationWhenInUseUsageDescription to Info.plist.

// pubspec: webview_flutter, webview_flutter_android, permission_handler
import 'package:flutter/material.dart';
import 'package:permission_handler/permission_handler.dart';
import 'package:webview_flutter/webview_flutter.dart';
import 'package:webview_flutter_android/webview_flutter_android.dart';

class KycPage extends StatefulWidget {
  const KycPage({super.key, required this.onboardingUrl});
  final String onboardingUrl;
  @override
  State<KycPage> createState() => _KycPageState();
}

class _KycPageState extends State<KycPage> {
  late final WebViewController controller;

  @override
  void initState() {
    super.initState();
    controller = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..setNavigationDelegate(NavigationDelegate(
        onNavigationRequest: (req) {
          final uri = Uri.parse(req.url);
          if (uri.scheme == 'myapp' && uri.host == 'kyc') {          // returnUrl hand-off
            Navigator.of(context).pop(uri.queryParameters['requestId']);
            return NavigationDecision.prevent;
          }
          return NavigationDecision.navigate;
        },
      ));
    final platform = controller.platform;
    if (platform is AndroidWebViewController) {
      platform.setMediaPlaybackRequiresUserGesture(false);
      platform.setOnPlatformPermissionRequest((request) async {
        final statuses = await [Permission.camera, Permission.locationWhenInUse].request();
        statuses[Permission.camera]!.isGranted ? request.grant() : request.deny();
      });
    }
    controller.loadRequest(Uri.parse(widget.onboardingUrl));
  }

  @override
  Widget build(BuildContext context) => Scaffold(body: SafeArea(child: WebViewWidget(controller: controller)));
}