Mono¶

Mono is an opt-in provider. Configure its server-side secret key and select it explicitly or set it as the default provider:

IDENTITY_MADE_EASY_PROVIDER=mono
MONO_SECRET_KEY=your_mono_secret_key
MONO_BASE_URL=https://api.withmono.com
MONO_HTTP_TIMEOUT=30
MONO_WEBHOOK_SECRET=your_mono_webhook_secret

The package sends Mono's mono-sec-key only from the backend. The API secret key and webhook shared secret serve different purposes. Mono test/live keys select the corresponding environment where supported; Watchlist Screening is documented as live-only. The default API base URL is https://api.withmono.com, and merely installing the package makes no live requests.

Use capabilities¶

Mono's operation families have distinct contracts; check interfaces before calling provider-specific methods:

use Alphabalex\IdentityMadeEasy\Contracts\MonoIdentityLookupDriverInterface;
use Alphabalex\IdentityMadeEasy\Contracts\MonoProveDriverInterface;
use Alphabalex\IdentityMadeEasy\Facades\Identity;

$mono = Identity::driver('mono');

if ($mono instanceof MonoIdentityLookupDriverInterface) {
    $result = $mono->lookupNin(['nin' => '12345678901']);
}

if ($mono instanceof MonoProveDriverInterface) {
    $session = $mono->initiateProve([
        'reference' => 'customer-123',
        'redirect_url' => 'https://example.test/verify/complete',
        'kyc_level' => 'custom',
        'identities' => ['bvn'],
    ]);
}

Supported capabilities:

MonoIdentityLookupDriverInterface: banks, account number, credit history, driver's license, address, passport, mashup, NIN, TIN, and phone-NIN operations.
MonoBvnIgreeDriverInterface: initiate, verify, and fetch details for BVN iGree sessions. Pass the initiation session ID to subsequent calls; verification/detail calls send it as x-session-id.
MonoCacLookupDriverInterface: CAC search, company details, previous-address and change-of-name history, profile, and status-report PDF. The history routes are deprecated by Mono and retained for compatibility; confirm availability with Mono before relying on them.
MonoWatchlistScreeningDriverInterface: screening submission and lookup, audit log, report PDF, and monitoring.
MonoProveDriverInterface: initiate and manage Prove customers.

The capability and operation reference lists every exposed method and route. JSON operations return decoded response arrays. CAC status and Watchlist report methods return Laravel Illuminate\Http\Client\Response instances so applications can preserve PDF bytes and response headers.

Webhooks¶

The package provides an opt-in VerifyMonoWebhookSecret middleware for application-owned POST routes. It checks the mono-webhook-secret header against MONO_WEBHOOK_SECRET using a constant-time comparison and responds with HTTP 401 when either value is missing or does not match.

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

Route::post('/webhooks/mono', [MonoWebhookController::class, 'handle'])
    ->middleware(VerifyMonoWebhookSecret::class);

This is a shared-secret header check, not a body HMAC signature. The package does not register routes, validate or process event envelopes, acknowledge events, or deduplicate deliveries. Your application owns those tasks. Mono may redeliver events; make processing idempotent and acknowledge only after successful acceptance. Confirm whether your Mono dashboard uses one webhook secret for Prove and Watchlist before sharing configuration. See webhooks and privacy.

Scope notes¶

This package documents verified operations; it is not a claim that all Mono products and routes are implemented. CAC change-of-name and previous-address routes are deprecated by Mono but exposed for compatibility; confirm availability before relying on them. Prove fetch/revoke identifiers are passed through as supplied, and documentation discrepancies remain for Watchlist report versioning. Consult Mono's provider documentation when a flow depends on ambiguous API behavior.