JSPM

verifly-sdk

1.0.2
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 2
  • Score
    100M100P100Q61893F
  • License MIT

Official Node.js SDK for Verifly - Inbound 2FA Verification System with HMAC-SHA256 Authentication

Package Exports

  • verifly-sdk
  • verifly-sdk/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (verifly-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Verifly SDK

Official Node.js SDK for Verifly - Inbound 2FA Verification System

npm version License: MIT

⚠️ Important: This SDK uses HMAC-SHA256 signature authentication. Both API key and secret key are required.

Features

  • 🔐 Inbound 2FA Verification - SMS, WhatsApp, Voice Call, Email
  • 🚀 Simple API - Easy-to-use promise-based interface
  • 🛡️ Webhook Verification - Secure webhook signature validation
  • 💪 TypeScript Support - Full type definitions included
  • ⚡ Error Handling - Custom error classes for better error management
  • 📝 Well Documented - Comprehensive examples and documentation

Installation

npm install verifly-sdk

Quick Start

const Verifly = require('verifly-sdk');

// Initialize client (BOTH keys required)
const verifly = new Verifly('your-api-key', {
  secretKey: 'your-secret-key'  // REQUIRED for API authentication
});

// Create verification session
const session = await verifly.verification.create({
  phone: '5551234567',
  methods: ['sms', 'whatsapp'],
  lang: 'tr',
  webhookUrl: 'https://mysite.com/webhook'
});

console.log('Iframe URL:', session.iframeUrl);
console.log('Session ID:', session.sessionId);

Table of Contents

Initialization

API Key & Secret Key

IMPORTANT: Both keys are REQUIRED for authentication:

Key Type Used For Required? Where to Find
API Key Request identification ✅ REQUIRED Dashboard → Application → API Key
Secret Key HMAC signature generation ✅ REQUIRED Dashboard → Application → Secret Key 
const Verifly = require('verifly-sdk');

// ✅ Basic configuration (both keys required)
const verifly = new Verifly('your-api-key', {
  secretKey: 'your-secret-key'  // REQUIRED
});

// ✅ Full configuration
const verifly = new Verifly('your-api-key', {
  secretKey: 'your-secret-key',         // REQUIRED: For HMAC signature
  timeout: 30000,                        // Optional: Request timeout (ms)
  debug: false                           // Optional: Enable debug logging
});

Options

Option Type Default Required Description
secretKey string - ✅ YES Application secret key (for HMAC signature generation)
timeout number 30000 No Request timeout in milliseconds
debug boolean false No Enable debug logging

Authentication Method

Verifly uses HMAC-SHA256 signature for API authentication:

X-API-Key: your-api-key
X-Signature: hmac-sha256(timestamp + payload, secretKey)
X-Timestamp: current-timestamp

The SDK automatically generates these headers for every request.

Verification

Create Verification Session

Create a new verification session with phone number and/or email.

const session = await verifly.verification.create({
  phone: '5551234567',              // Optional
  email: 'user@example.com',        // Optional
  methods: ['sms', 'whatsapp'],     // Optional: sms, whatsapp, call, email
  lang: 'tr',                        // Optional: en, tr (default: en)
  webhookUrl: 'https://mysite.com/webhook', // Optional
  redirectUrl: 'https://mysite.com/success', // Optional
  timeout: 5,                        // Optional: 1-15 minutes (default: 2)
  data: { userId: '12345', orderId: 'ORD-789' } // Optional: Custom data (max 100KB)
});

// Use the iframe URL in your application
console.log(session.iframeUrl);

Response:

{
  sessionId: 'abc123...',
  iframeUrl: 'https://www.verifly.net/verify/iframe/abc123...',
  expiresAt: '2025-01-14T20:00:00.000Z',
  allowedMethods: ['sms', 'whatsapp'],
  method: null,  // or 'sms' if only one method
  userInputRequired: false
}

Get Verification Status

Check the current status of a verification session.

const status = await verifly.verification.get('session-id');

console.log('Status:', status.status);
// Possible values: 'pending', 'waiting', 'verified', 'failed', 'expired'

Response:

{
  sessionId: 'abc123...',
  status: 'verified',
  method: 'sms',
  verificationCode: '123456',
  recipientContact: '5551234567',
  verifiedAt: '2025-01-14T19:55:00.000Z',
  // ... other fields
}

Select Verification Method

If multiple methods are available, select one.

await verifly.verification.selectMethod('session-id', {
  method: 'sms',
  recipientContact: '5551234567'  // If not provided in create
});

Cancel Verification Session

Cancel an active verification session (user can retry later).

await verifly.verification.cancel('session-id');

Abort Verification Session

Permanently abort a verification session (cannot be retried).

await verifly.verification.abort('session-id');

Difference:

  • cancel() - Temporary cancellation, user can restart
  • abort() - Permanent abort, session is completely terminated

Get Balance

Get account balance and recent transactions.

const balance = await verifly.verification.getBalance();

console.log('Balance:', balance.balance, balance.currency);
console.log('Recent transactions:', balance.recentTransactions);

Response:

{
  balance: 1500.00,
  currency: 'TRY',
  userId: '...',
  email: 'user@example.com',
  recentTransactions: [
    {
      type: 'credit',
      amount: 500,
      description: 'Balance added',
      createdAt: '2025-01-14T...'
    },
    // ... more transactions
  ]
}

Webhooks

Note: Secret key is already required for SDK initialization, so webhook features are automatically available.

Verify Webhook Signature

Verify that a webhook request actually came from Verifly.

const express = require('express');
const app = express();

// Initialize with secret key (REQUIRED for webhooks)
const verifly = new Verifly('your-api-key', {
  secretKey: 'your-secret-key'
});

app.use(express.json());

app.post('/webhook/verifly', (req, res) => {
  const signature = req.headers['x-verifly-signature'];
  
  // Verify signature (requires secretKey)
  const isValid = verifly.webhook.verify(req.body, signature);
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook...
  res.status(200).send('OK');
});

Handle Webhook Events

Process different webhook event types.

app.post('/webhook/verifly', (req, res) => {
  const signature = req.headers['x-verifly-signature'];
  
  try {
    // Construct and verify event
    const event = verifly.webhook.constructEvent(req.body, signature);
    
    // Handle event types
    switch (event.type) {
      case 'verification.success':
        console.log('✅ Verification successful:', event.data.sessionId);
        console.log('Custom data:', event.data.customData); // Your custom data from create()
        // Update user in database, send confirmation, etc.
        break;
      
      case 'verification.failed':
        console.log('❌ Verification failed:', event.data.sessionId);
        break;
      
      case 'verification.expired':
        console.log('⏰ Verification expired:', event.data.sessionId);
        break;
      
      case 'verification.cancelled':
        console.log('🚫 Verification cancelled:', event.data.sessionId);
        break;
    }
    
    res.status(200).send('OK');
    
  } catch (error) {
    console.error('Webhook error:', error.message);
    res.status(400).send('Error');
  }
});

Webhook Response Helper

Use the built-in response helper for cleaner code.

app.post('/webhook/verifly', (req, res) => {
  const webhook = verifly.webhook.response(res);
  
  try {
    const signature = req.headers['x-verifly-signature'];
    const event = verifly.webhook.constructEvent(req.body, signature);
    
    // Process event...
    
    webhook.success(); // Responds with 200 OK
    
  } catch (error) {
    if (error.message.includes('signature')) {
      webhook.unauthorized('Invalid signature'); // 401
    } else {
      webhook.error('Processing error', 500); // 500
    }
  }
});

Error Handling

The SDK provides custom error classes for better error management.

const { errors } = require('verifly-sdk');

try {
  const session = await verifly.verification.create({
    phone: '123',  // Too short
    methods: ['sms']
  });
} catch (error) {
  if (error instanceof errors.ValidationError) {
    console.log('Validation error:', error.message);
    console.log('Response:', error.response);
  }
  
  if (error instanceof errors.InsufficientBalanceError) {
    console.log('Insufficient balance!');
    console.log('Current:', error.balanceData.currentBalance);
    console.log('Required:', error.balanceData.minimumRequired);
  }
  
  if (error instanceof errors.AuthenticationError) {
    console.log('Invalid API key');
  }
}

Error Classes

Error Class Status Code Description
VeriflyError - Base error class
AuthenticationError 401 Invalid API key
ValidationError 400 Invalid parameters
InsufficientBalanceError 402 Insufficient account balance
NotFoundError 404 Resource not found
RateLimitError 429 Rate limit exceeded
ServerError 500 Server error

TypeScript

The SDK includes full TypeScript type definitions.

import Verifly, { 
  VeriflyOptions, 
  CreateVerificationParams,
  VerificationSession 
} from 'verifly-sdk';

const options: VeriflyOptions = {
  debug: true
};

const verifly = new Verifly('your-api-key', options);

const params: CreateVerificationParams = {
  phone: '5551234567',
  methods: ['sms', 'whatsapp'],
  lang: 'tr'
};

const session: VerificationSession = await verifly.verification.create(params);

Examples

Check the /examples directory for complete examples:

Running Examples

cd examples

# Edit the API key in the example file
nano basic.js

# Run the example
node basic.js

Error Handling

The SDK uses exceptions for error handling (standard Node.js practice).

Try-Catch Pattern

const Verifly = require('verifly-sdk');
const { errors } = Verifly;

try {
  const session = await verifly.verification.create({
    phone: '5551234567',
    methods: ['sms']
  });
  
  console.log('✅ Success:', session);
  
} catch (error) {
  // Handle different error types
  if (error instanceof errors.AuthenticationError) {
    console.error('❌ Authentication failed:', error.message);
    // Check your API key and secret key
    
  } else if (error instanceof errors.InsufficientBalanceError) {
    console.error('❌ Insufficient balance:', error.message);
    console.log('Balance data:', error.balanceData);
    // User needs to add balance
    
  } else if (error instanceof errors.ValidationError) {
    console.error('❌ Validation error:', error.message);
    // Fix input parameters
    
  } else if (error instanceof errors.RateLimitError) {
    console.error('❌ Rate limit exceeded:', error.message);
    // Wait and retry
    
  } else {
    console.error('❌ Unknown error:', error.message);
  }
}

Error Types

Error Class HTTP Status Description
AuthenticationError 401 Invalid API key or secret key
ValidationError 400 Invalid request parameters
InsufficientBalanceError 402 Not enough account balance
NotFoundError 404 Session or resource not found
RateLimitError 429 Too many requests
ServerError 500 Server error

Helper Function (Optional)

If you prefer { success, error } format:

async function safeVerify(phone) {
  try {
    const session = await verifly.verification.create({
      phone,
      methods: ['sms', 'whatsapp']
    });
    return { success: true, data: session };
  } catch (error) {
    return {
      success: false,
      error: error.message,
      errorType: error.constructor.name,
      statusCode: error.statusCode
    };
  }
}

// Usage
const result = await safeVerify('5551234567');
if (result.success) {
  console.log('✅', result.data);
} else {
  console.log('❌', result.error);
}

API Reference

Verifly

Constructor

new Verifly(apiKey, options?)

Methods

  • setSecretKey(secretKey) - Set application secret key
  • setDebug(enabled) - Enable/disable debug mode

Verification

Methods

  • create(params) - Create verification session
  • get(sessionId) - Get session status
  • selectMethod(sessionId, params) - Select verification method
  • cancel(sessionId) - Cancel session (temporary)
  • abort(sessionId) - Abort session (permanent)
  • getBalance() - Get account balance and transactions

Webhook

Methods

  • verify(payload, signature) - Verify webhook signature
  • generateSignature(payload) - Generate signature (for testing)
  • constructEvent(payload, signature) - Construct event object
  • response(res) - Create response helper

Support

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Made with ❤️ by the SOCIFLY SOFTWARE LTD