Quickstart Guide

Integrate Solidus Verify into your application in under 15 minutes. This guide walks you through creating a verification session, handling the user redirect, and verifying the resulting credential.

Prerequisites

Node.js 18.0 or later installed
A Solidus Verify account (Sign up for a Sandbox account)
A Sandbox API Key from your dashboard

1. Install the SDK

Install the official Solidus Verify package via npm, yarn, or pnpm.

bash

$ npm install @solidus/verify
$ yarn add @solidus/verify

2. Initialize the Client

Initialize the Solidus SDK using your secret API key. Never expose your secret key in client-side code.

TypeScript

import { SolidusVerify } from '@solidus/verify';

const verify = new SolidusVerify({
  apiKey: process.env.SOLIDUS_SECRET_KEY,
  environment: 'sandbox' // or 'production'
});

3. Create a Verification Session

Create a session when your user needs to be verified. You'll receive a URL to redirect them to.

TypeScript

const session = await verify.sessions.create({
  did: "did:solidus:mainnet:7a3b8c9d2e1f4a6b",
  level: 2, // 1 = Basic, 2 = Passport + Liveness
  redirectUrl: "https://yourapp.com/onboarding/complete",
  metadata: {
    internalUserId: "usr_7a3b8c9d"
  }
});

console.log(session.url); // https://verify.solidus.network/s/...

4. Redirect the User

Redirect your user to the generated URL. They will complete the fully hosted, white-labeled verification flow seamlessly on mobile or desktop.

1. ID Document Upload

2. Biometric Liveness Check

TypeScript

// Example in an Express.js route handler
app.post('/api/verify', async (req, res) => {
  const session = await verify.sessions.create({ /*...*/ });
  res.redirect(302, session.url);
});

5. Handle the Webhook

Listen for the kyc.completed webhook event to securely confirm when a user finishes the flow.

TypeScript

app.post('/webhooks/solidus', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['solidus-signature'];
  
  try {
    const event = verify.webhooks.constructEvent(
      req.body,
      signature,
      process.env.SOLIDUS_WEBHOOK_SECRET
    );

    if (event.type === 'kyc.completed') {
      const sessionId = event.data.session_id;
      // Update user status in your database
    }
    res.status(200).send();
  } catch (err) {
    res.status(400).send(`Webhook Error: ${err.message}`);
  }
});

6. Verify the Credential

Once verified, fetch the W3C Verifiable Credential. This payload contains cryptographic proof of the user's KYC status.

TypeScript

// Retrieve the verified credential using the session ID
const credential = await verify.credentials.retrieve({ 
  sessionId: "vsn_9f8e7d6c5b4a3291" 
});

// Optionally, verify its cryptographic signature locally
const isValid = await verify.credentials.verify(credential);
if (isValid) {
  console.log("Credential signature is valid and trusted.");
}

Live Preview Monitor

Console

// Install dependencies to begin...