Skip to main content

Headless Engine

For developers who require 100% control over the user interface, the Headless Engine via the KycSDK class provides raw API orchestration.

The KycSDK manages the state machine, API interactions, and workflow steps while leaving the rendering entirely up to you.

Initializing the Engine​

import { KycSDK } from '@ha-shem/Spidify-sdk';

const sdk = new KycSDK({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://your-backend.com'
});

// Bootstraps the session
await sdk.init('unique_user_id');
sdk.start();

Implementing Steps​

Instead of Spidify rendering a UI, you listen to events and build your own React, Vue, or Vanilla JS components.

Example: Custom OTP Step​

// 1. Listen for the OTP step
sdk.on('step_started', (event) => {
  if (event.step === 'otp-verification') {
    // Show your custom OTP input UI
    showMyCustomOtpScreen();
  }
});

// 2. User clicks "Send OTP"
async function handleSendOtp(phoneNumber) {
  await sdk.sendOtp({ phoneNumber });
}

// 3. User submits the code
async function handleOtpSubmit(code) {
  try {
    await sdk.submitOtp(code);
    // Move to next step manually or rely on the state machine event
  } catch (err) {
    showError('Invalid code!');
  }
}

Available Headless Methods​

The KycSDK exposes methods for all standard KYC steps:

  • sendOtp(contact)
  • submitOtp(otp)
  • uploadDocument(type, subtype, base64)
  • initiateLiveness(contact)
  • startLiveness()
  • screenCompliance(firstName, lastName)
  • verifyBvn(data)

See the API Reference for detailed method signatures.