2.2.2.1 C#/.NET

VerifySpeed C#/.NET Client Library Documentation

The VerifySpeed .NET Client Library allows you to seamlessly integrate user verification features into your application. With support for multiple verification methods like Telegram, WhatsApp, and SMS, you can ensure a secure and reliable verification process for your users.

Setup

Step 1: Intall the Package

First, make sure you have installed the VerifySpeed package:

dotnet add package VerifySpeed.VSCSharp

Step 2: Service Registration

Next, add the VerifySpeed services to your application's dependency injection container in the Startup.cs or Program.cs file.

.NET 6+

using VSCSharp;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

// Register VerifySpeed services with your server key.
builder.Services.AddVerifySpeed("YOUR_SERVER_KEY");

// Add other services

WebApplication app = builder.Build();

// Add your middlewares

app.Run();

.NET 5

using VSCSharp;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // Register VerifySpeed services with your server key
        services.AddVerifySpeed("YOUR_SERVER_KEY");

        // Add other services
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
    // Add your middlewares
    }
}

Usage

Below are examples of how to use the VerifySpeed client in your C# application.

note

Please read Verification Flow to understand the verification process.

1. Initializing the Client

Before creating a verification, you need to initialize the verification process to retrieve the available verification methods.

using System;
using System.Threading.Tasks;
using VSCSharp.Clients;
using VSCSharp.Exceptions;

public class VerifySpeedExample
{
    private readonly IVerifySpeedClient verifySpeedClient;

    public VerifySpeedExample(IVerifySpeedClient verifySpeedClient)
    {
        this.verifySpeedClient = verifySpeedClient;
    }

    public async Task InitializeVerificationAsync()
    {
        try
        {
            //TODO: Replace with the actual remote client IP address.
            string clientIp = "192.168.1.1";

            Initialization initialization = await verifySpeedClient.InitializeAsync(clientIp);
            
            Console.WriteLine("Available Verification Methods:");
            foreach (Method availableMethod in initialization.AvailableMethods)
            {
                Console.WriteLine($"- {availableMethod.DisplayName} ({availableMethod.MethodName})");
            }

            // in most cases, you may return the available methods to client.
        }
        catch (FailedInitializationException exeption)
        {
            Console.WriteLine($"Initialization failed: {exeption.Message}");
        }
    }
}

2. Creating a Verification

Once initialized, you can create a verification using the desired method (e.g., Telegram Message, WhatsApp Message).

note

NOTE: Please read Verification Flow and Verification Methods to understand the verification process.

using System;
using System.Threading.Tasks;
using VSCSharp.Clients;
using VSCSharp.Enums;
using VSCSharp.Exceptions;
using VSCSharp.Models.Commons;

public class VerificationCreationExample
{
    private readonly IVerifySpeedClient verifySpeedClient;

    public VerificationCreationExample(IVerifySpeedClient verifySpeedClient)
    {
        this.verifySpeedClient = verifySpeedClient;
    }

    public async Task CreateVerificationAsync()
    {
        try
        {
            //TODO: Replace with the actual remote client IP address.
            string clientIp = "192.168.1.1";

            CreatedVerification createdVerification = await verifySpeedClient.CreateVerificationAsync(
                methodName: "telegram-message",
                clientIPv4Address: clientIp,
                language: "ar"
            );

            Console.WriteLine($"Verification Method: {createdVerification.MethodName}");
            Console.WriteLine($"Verification Key: {createdVerification.VerificationKey}");
            Console.WriteLine($"Deep Link: {createdVerification.DeepLink}");

            // Use should return VerificationKey with DeepLink to the your mobile/web app
        }
        catch (FailedCreateVerificationException exeption)
        {
            Console.WriteLine($"Failed to create verification: {exeption.Message}");
        }
    }
}

3. Decrypting Verification Tokens (Recommended)

This is the recommended approach for verifying tokens. The EncryptionTool class allows you to decrypt verification tokens directly on your server without making additional API calls. This method is faster, more secure, and gives you full control over the verification process.

Client's Built-in Method

The IVerifySpeedClient also provides a built-in decryption method that uses your configured server key:

public class ClientDecryptionExample
{
    private readonly IVerifySpeedClient verifySpeedClient;

    public ClientDecryptionExample(IVerifySpeedClient verifySpeedClient)
    {
        verifySpeedClient = verifySpeedClient;
    }

    public void DecryptTokenUsingClient(string encryptedToken)
    {
        try
        {
            // Uses the server key configured during service registration
            VerificationResult result = verifySpeedClient.DecryptVerificationToken(encryptedToken);
            
            Console.WriteLine($"Decrypted Phone Number: {result.PhoneNumber}");
            Console.WriteLine($"Verification Method: {result.MethodName}");
            Console.WriteLine($"Date of Verification: {result.DateOfVerification}");
            
            // Process the verified user
            ProcessVerifiedUser(result.PhoneNumber, result.MethodName, result.DateOfVerification);
        }
        catch (InvalidVerificationTokenException ex)
        {
            Console.WriteLine($"Token validation failed: {ex.Message}");
        }
        catch (FailedDecryptingVerificationTokenException ex)
        {
            Console.WriteLine($"Token decryption failed: {ex.Message}");
        }
    }
    
    private void ProcessVerifiedUser(string phoneNumber, string methodName, DateTime verificationDate)
    {
        // Implement your business logic here
        Console.WriteLine($"Processing verified user: {phoneNumber} via {methodName}");
    }
}

This approach is convenient when you want to use the server key that was configured during service registration without having to pass it explicitly.

EncryptionTool Extension Method

The DecryptVerificationToken method is implemented as an extension method on the string type, making it easy to use:

// Direct usage on the encrypted token string
string encryptedToken = "your_encrypted_token_here";
string serverKey = "your_server_key_here";

VerificationResult result = encryptedToken.DecryptVerificationToken(serverKey);

// Or using the EncryptionTool class directly
var encryptionTool = new EncryptionTool();
VerificationResult result2 = encryptionTool.DecryptVerificationToken(encryptedToken, serverKey);

This approach gives you more flexibility and control over the decryption process.

4. Verifying a Token via API (Alternative Method)

Alternative approach: If you cannot decrypt the token on your own or prefer to use the API endpoint, you can verify tokens through the VerifySpeed API. This method makes an additional network call but may be useful in certain scenarios.

note

Recommendation: Use the decryption method above for better performance and security. Only use this API method if you cannot implement the decryption logic on your server.

using System;
using System.Threading.Tasks;
using VSCSharp.Clients;
using VSCSharp.Exceptions;

public class TokenVerificationExample
{
    private readonly IVerifySpeedClient verifySpeedClient;

    public TokenVerificationExample(IVerifySpeedClient verifySpeedClient)
    {
        verifySpeedClient = verifySpeedClient;
    }

    public async Task VerifyTokenAsync(string token)
    {
        try
        {
            VerificationResult result = verifySpeedClient.DecryptVerificationToken(token);
            Console.WriteLine($"Verified Phone Number: {result.PhoneNumber}");
            Console.WriteLine($"Verification Method: {result.MethodName}");
            Console.WriteLine($"Date of Verification: {result.DateOfVerification}");
        }
        catch (FailedVerifyingTokenException exeption)
        {
            Console.WriteLine($"Token verification failed: {exeption.Message}");
        }
        catch (FailedVerifyingTokenException exeption)
        {
            Console.WriteLine($"Token verification failed: {exeption.Message}");
        }
    }
}

Models

Initialization Response

• Initialization: Contains a list of available verification methods.

  public record Initialization
  {
      public List<Method> AvailableMethods { get; init; } = new();
  }
  
  public record Method
  {
      public string MethodName { get; init; } = null!;
      public string DisplayName { get; init; } = null!;
  }

Created Verification

• CreatedVerification: Provides details on the created verification, such as a key, its method name, and deep link (not null if method name is whatsapp-messege or telegram-message).

  public record CreatedVerification
  {
      public string MethodName { get; init; } = null!;
      public string VerificationKey { get; init; } = null!;
      public string? DeepLink { get; init; }
  }

Verification Result

• VerificationResult: Represents the outcome of verifying a user's token.

  public record VerificationResult
  {
      public string MethodName { get; init; } = null!;
      public DateTime DateOfVerification { get; init; }
      public string PhoneNumber { get; init; } = null!;
  }

Exceptions

Handle the following exceptions

• FailedInitializationException: Thrown when initialization fails.
• FailedCreateVerificationException: Thrown when verification creation fails.
• FailedVerifyingTokenException: Thrown when token verification fails.
• InvalidVerificationTokenException: Thrown when the verification token is null, empty, or has an invalid format.
• FailedDecryptingVerificationTokenException: Thrown when token decryption fails due to cryptographic errors.

API Example

Here is an use case example of this library for varifying users phone number.

using Microsoft.AspNetCore.Mvc;
using VSCSharp.Clients;
using VSCSharp.Models.Commons;
using VSCSharp.Enums;

[ApiController]
[Route("api/[controller]")]
public class VerificationController : ControllerBase
{
    private readonly IVerifySpeedClient verifySpeedClient;

    public VerificationController(IVerifySpeedClient verifySpeedClient)
    {
        verifySpeedClient = verifySpeedClient;
    }

    [HttpPost("initialize")]
    public async Task<IActionResult> PostVerificationInitialization()
    {
        try
        {
            var clientIp = HttpContext.Connection.RemoteIpAddress?.ToString();
            // NOTE: If your API is behind proxy or load balancer, get client's IP from 'X-Forwarded-For' header

            Initialization initialization = await verifySpeedClient.InitializeAsync(clientIp);

            return Ok(initialization);
        }
        catch (Exception exeption)
        {
            return BadRequest(exeption.Message);
        }
    }

    [HttpPost("create")]
    public async Task<IActionResult> PostVerificationCreation([FromBody] PostVerificationCreationRequest request)
    {
        try
        {
            var clientIp = HttpContext.Connection.RemoteIpAddress?.ToString();
            // NOTE: If your API is behind proxy or load balancer, get client's IP from 'X-Forwarded-For' header

            CreatedVerification verification = await verifySpeedClient.CreateVerificationAsync(
                request.MethodType,
                clientIp
            );

            return Ok(verification);
        }
        catch (Exception exeption)
        {
            return BadRequest(exeption.Message);
        }
    }

    [HttpGet("verify/{token}")]
    public async Task<IActionResult> GetVerificationResult(string token)
    {
        try
        {
            // Option 1: Use local decryption (recommended - faster and more secure)
            // Uses the server key configured during service registration
            VerificationResult result = verifySpeedClient.DecryptVerificationToken(token);
            
            // Option 2: Use API verification (makes HTTP call)
            // VerificationResult result = await verifySpeedClient.VerifyTokenAsync(token);
            
            // Now you can use verified phone number inside result object
            Console.WriteLine($"Verified Phone Number: {result.PhoneNumber}");

            return Ok(result);
        }
        catch (InvalidVerificationTokenException ex)
        {
            return BadRequest($"Invalid token: {ex.Message}");
        }
        catch (FailedDecryptingVerificationTokenException ex)
        {
            return BadRequest($"Decryption failed: {ex.Message}");
        }
        catch (Exception exeption)
        {
            return BadRequest(exeption.Message);
        }
    }
}

public class PostVerificationCreationRequest
{
    [Required]
    public string MethodType { get; set; }
}

License

This package is distributed under the MIT License.