Integration Guide

This guide explains how to integrate the Verification API into any application. Examples added are from Reference Beneficiary and Provider Toasters

Basic API Integration

The Verification API is technology-agnostic and can be integrated into any system by making a simple HTTP POST request to the /verification endpoint.

curl -X POST http://your-domain-or-ip:{{PORT}}/verification \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {
      "id": "12345",
      "type": "VerifiableCredential",
      "issuer": "https://example.com",
      "credentialSubject": {
        "id": "did:example:123",
        "name": "John Doe"
      }
    },
    "config": {
      "method": "online",
      "issuerName": "dhiway"
    }
  }'

How to use this example:

• Replace your-domain-or-ip and {{PORT}} with your actual deployment details.

• Send a POST request with this JSON structure from your system.

• The response will indicate whether the credential is valid or not.

Example # 1 Verification API Integration in Reference Beneficiary App

The Verification SDK is integrated into the beneficiary backend to verify Verifiable Credentials (VC) during direct scan & document uploads and fetching document from wallet.

Document Upload API

Endpoint Details

POST /api/users/wallet/user_docs
Authorization: Bearer <JWT_TOKEN>

1. User uploads document via /user_docs endpoint

2. API internally calls verification service before storage

3. Document is only stored if verification succeeds

Verification Implementation

Configuration

VC_VERIFICATION_SERVICE_URL=<verification_service_url>
VC_DEFAULT_ISSUER_NAME=dhiway  # default issuer

Implementation

Core verification method: verifyVcWithApi

// Verification payload
{
  "credential": "<VC_DATA>",
  "config": {
    "method": "online",
    "issuerName": "dhiway"
  }
}

Integration Points

The SDK is called at these points:

• Document upload API: createUserDocsNew

• Document processing: processSingleUserDoc

Example # 2 Verification API Integration in Reference Provider App

The Verification SDK is integrated into the provider middleware to verify Verifiable Credentials (VC) submitted by applicants through application file uploads and verification requests.

Verification API Endpoint

Endpoint Details

• POST /verification/verify-vcs

• Authorization: Bearer JWT Token required

• Controller: src/verifications/verifications.controller.ts

Process Flow

1. User submits verification request via /verify-vcs endpoint

2. API internally calls Verification SDK before updating database

3. Application verification status is updated based on SDK response

Verification Implementation

Configuration

VERIFICATION_SERVICE_URL=<verification_service_url>
DEFAULT_ISSUER_NAME=dhiway  # default issuer

Implementation Core verification method: verifyApplicationVcs in src/verifications/verification.service.ts

// Environment check
const apiUrl = process.env.VERIFICATION_SERVICE_URL;
if (!apiUrl) {
  return this.buildResponse(false, 500, 'VERIFICATION_SERVICE_URL is not defined');
}

// Verification payload
const response = await lastValueFrom(
  this.httpService.post(apiUrl, {
    "credential": parsedData,    // VC document content
    "config": {
      "method": "online",
      "issuerName": "dhiway"     // From DEFAULT_ISSUER_NAME or file metadata
    }
  })
);

Response Handling

// Update verification status based on SDK response
verificationStatus: {
  status: isValid ? 'Verified' : 'Unverified',
  verificationErrors: response.data.errors || []
}

Integration Points

The SDK integration flow:

• Verification Request: verifyApplicationVcs method.

• File Processing: Load and parse VC documents from application files.

• API Call: Send processed VC data to Verification SDK.

• Status Updates: Update database with verification results (both success and failure).