Skip to content

IdenVault

IdenVault is an opt-in, server-to-server provider. Start with a sandbox API key; sandbox uses the same routes and response shapes as live, returns fixture data, and is not billed.

IDENVAULT_API_KEY=your_idenvault_api_key
IDENVAULT_BASE_URL=https://idenvault.com/api/v1
IDENVAULT_HTTP_TIMEOUT=30
IDENVAULT_WEBHOOK_SECRET=your_idenvault_webhook_secret

Select it as the configured default with IDENTITY_MADE_EASY_PROVIDER=idenvault, or resolve it directly using Identity::driver('idenvault'). Keep the API key server-side and use IDENVAULT_WEBHOOK_SECRET only for inbound webhook verification.

Verify an identity

Verification calls require an idempotency key generated and stored by your application for each logical operation. Reuse that same key if retrying that operation:

use Alphabalex\IdentityMadeEasy\Contracts\IdenVaultIdentityVerificationDriverInterface;
use Alphabalex\IdentityMadeEasy\Facades\Identity;
use Illuminate\Support\Str;

$idenvault = Identity::driver('idenvault');
$operationKey = (string) Str::uuid(); // Persist this to reuse it on retry.

if ($idenvault instanceof IdenVaultIdentityVerificationDriverInterface) {
    $response = $idenvault->verifyNinBasic(
        ['nin' => '12345678901', 'request_reason' => 'creditBackgroundCheck'],
        $operationKey,
    );

    $data = $response->json();
    $status = $response->status();
    $requestReference = $response->header('X-Request-Ref');
}

The package forwards the payload unchanged; it does not collect consent or choose request_reason for you. Every live identity query can return real personal information. Your application is the data controller: obtain and retain appropriate consent or another lawful basis before making a request, send a truthful reason when required, and avoid storing unnecessary data.

Available operations

IdenVaultIdentityVerificationDriverInterface:

  • verifyNinBasic($payload, $idempotencyKey)
  • verifyNinMatch($payload, $idempotencyKey)
  • verifyPhone($payload, $idempotencyKey)
  • verifyBvn($payload, $idempotencyKey)
  • verifyBvnBasic($payload, $idempotencyKey)
  • verifyShareCode($payload, $idempotencyKey)
  • verifyDemography($payload, $idempotencyKey)

IdenVaultBankVerificationDriverInterface:

  • verifyBankAccount($payload, $idempotencyKey)
  • getBanks()

IdenVaultAccountDriverInterface:

  • getAccountBalance()
  • getMeta()

All operations return Laravel Illuminate\Http\Client\Response objects. Inspect status, JSON/body, and headers. Audit/accounting headers may include X-Request-Ref, X-Request-Id, X-Charge-Amount, X-Wallet-Balance, X-Cache, X-IdenVault-Mode, X-API-Version, rate-limit metadata, and Retry-After. Phone lookup may return a top-level JSON array, so use $response->json() instead of assuming an object.

Non-2xx responses are returned unchanged, including structured errors. Handle insufficient balance (402), validation failures (422), rate limiting (429), and upstream errors (502) at your application boundary. Respect Retry-After; after a timeout or a safely retryable error, reuse the same Idempotency-Key. A live NIMC not-found response may still be billed; sandbox requests are not billed. Preserve request references for support while minimizing retained identity data.

Wallet webhook signature

VerifyIdenVaultWebhookSignature is opt-in middleware for an application-owned route. It validates the raw request body against the timestamped HMAC signature and enforces a default 300-second timestamp tolerance:

use Alphabalex\IdentityMadeEasy\Http\Middleware\VerifyIdenVaultWebhookSignature;
use Illuminate\Support\Facades\Route;

Route::post('/webhooks/idenvault', [IdenVaultWebhookController::class, 'handle'])
    ->middleware(VerifyIdenVaultWebhookSignature::class);

The expected header shape is X-IdenVault-Signature: t=<unix timestamp>,v1=<hex> and the signed message is {timestamp}.{raw body} with HMAC-SHA256 using IDENVAULT_WEBHOOK_SECRET. Invalid or missing configuration/signatures return HTTP 401. Do not parse or re-encode the body before this middleware runs.

The package does not register webhook routes or process events. Your application is responsible for event validation, durable handling, deduplication (use the provider event ID), and returning a timely 2xx acknowledgment. Do not log webhook bodies or sensitive identifiers. See webhooks and privacy.