IDEX API reference

curl "https://idex.com.ng/api/v1/balance" \
  -H "Authorization: Bearer idex_live_a1b2c3d4e5f6a7b8_REPLACE_WITH_YOUR_SECRET" \
  -H "Accept: application/json"

{
  "success": true,
  "request_id": "b7f2c81d9a4e4c05",
  "status": "ok",
  "data": {
    "balance": 4820.50,
    "currency": "NGN",
    "account_type": "business"
  },
  "timestamp": "2026-08-18T11:04:23+01:00"
}

Authorization: Bearer idex_live_a1b2c3d4e5f6a7b8_REPLACE_WITH_YOUR_SECRET

{
  "success": false,
  "request_id": "5c0a71e4b8d34f92",
  "status": "error",
  "error": {
    "code": "invalid_key",
    "message": "The API key is invalid."
  },
  "timestamp": "2026-08-18T11:06:02+01:00"
}

POST /api/v1/nin/verify HTTP/1.1
Host: idex.com.ng
Authorization: Bearer idex_live_a1b2c3d4e5f6a7b8_REPLACE_WITH_YOUR_SECRET
Content-Type: application/json
Accept: application/json
User-Agent: acme-onboarding/1.4

{
  "service": "NIN_BASIC",
  "nin": "12345678901",
  "consent": true
}

curl -X POST "https://idex.com.ng/api/v1/nin/verify" \
  -H "Authorization: Bearer idex_live_a1b2c3d4e5f6a7b8_REPLACE_WITH_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --max-time 90 \
  -d '{
        "service": "NIN_BASIC",
        "nin": "12345678901",
        "consent": true
      }'

<?php

$apiKey = getenv('IDEX_API_KEY');   // never hard-code the key

$payload = json_encode([
    'service' => 'NIN_BASIC',
    'nin'     => '12345678901',
    'consent' => true,
]);

$ch = curl_init('https://idex.com.ng/api/v1/nin/verify');

curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 90,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$raw    = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
$failed = curl_errno($ch) !== 0;
curl_close($ch);

// A transport failure is NOT a failed verification. Reconcile, do not resubmit.
if ($failed) {
    reconcileWithIdex();   // see "Full examples"
    exit;
}

$body = json_decode((string) $raw, true);

if ($status === 200 && !empty($body['success'])) {
    // Persist the reference first, then use the record.
    saveReference($body['reference']);
    echo $body['data']['first_name'] . ' ' . $body['data']['last_name'];
} else {
    $code = $body['error']['code'] ?? 'internal_error';
    echo 'Verification not completed: ' . $code;
}

// Server-side only. This file must never reach a browser bundle.
const IDEX_KEY = process.env.IDEX_API_KEY;

async function verifyNin(nin) {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 90000);

  let response;
  try {
    response = await fetch('https://idex.com.ng/api/v1/nin/verify', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${IDEX_KEY}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({ service: 'NIN_BASIC', nin, consent: true }),
      signal: controller.signal
    });
  } finally {
    clearTimeout(timeout);
  }

  const body = await response.json();

  if (!response.ok || !body.success) {
    const error = new Error(body.error?.message ?? 'Verification failed');
    error.code = body.error?.code ?? 'internal_error';
    error.requestId = body.request_id;
    error.reference = body.reference ?? null;
    throw error;
  }

  return body;
}

import os
import requests

BASE_URL = "https://idex.com.ng/api/v1"
API_KEY = os.environ["IDEX_API_KEY"]

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "User-Agent": "acme-onboarding/1.4",
})


def verify_nin(nin: str, service: str = "NIN_BASIC") -> dict:
    response = session.post(
        f"{BASE_URL}/nin/verify",
        json={"service": service, "nin": nin, "consent": True},
        timeout=90,
    )

    body = response.json()

    if response.status_code != 200 or not body.get("success"):
        error = body.get("error", {})
        raise RuntimeError(f"{error.get('code', 'internal_error')}: {error.get('message', '')}")

    return body


record = verify_nin("12345678901")
print(record["reference"], record["data"].get("first_name"))

{
  "success": true,
  "request_id": "9f1c2d7a4b6e48f0",
  "status": "successful",
  "reference": "IDX-260818-4B7E1C9A02",
  "service": "NIN_BASIC",
  "message": "Verification completed.",
  "amount": 150.00,
  "currency": "NGN",
  "balance": 4670.50,
  "refunded": false,
  "data": {
    "nin": "12345678901",
    "first_name": "ADAEZE",
    "middle_name": "NGOZI",
    "last_name": "OKONKWO",
    "date_of_birth": "1991-04-17",
    "gender": "female",
    "phone_number": "08012345678",
    "state_of_origin": "ANAMBRA"
  },
  "timestamp": "2026-08-18T11:04:23+01:00"
}

{
  "success": false,
  "request_id": "1d4e77a0c9b24e31",
  "status": "refunded",
  "reference": "IDX-260818-7C21A0FE93",
  "service": "NIN_BASIC",
  "amount": 150.00,
  "currency": "NGN",
  "balance": 4820.50,
  "refunded": true,
  "error": {
    "code": "not_found",
    "message": "No record was found for that National Identification Number."
  },
  "timestamp": "2026-08-18T11:09:55+01:00"
}

{
  "success": false,
  "request_id": "3ab90f1e5c7d4a68",
  "status": "error",
  "error": {
    "code": "service_unavailable",
    "message": "NIN Basic Verification is not yet available. No charge has been made."
  },
  "timestamp": "2026-08-18T11:11:07+01:00"
}

curl -X POST "https://idex.com.ng/api/v1/bvn/verify" \
  -H "Authorization: Bearer idex_live_a1b2c3d4e5f6a7b8_REPLACE_WITH_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --max-time 90 \
  -d '{
        "service": "BVN_BASIC",
        "bvn": "22123456789",
        "consent": true
      }'

<?php

/**
 * Confirm a BVN exists without pulling any personal data.
 * BVN_VALIDATION is the data-minimising choice for an onboarding gate.
 */
function idexValidateBvn(string $bvn): bool
{
    $ch = curl_init('https://idex.com.ng/api/v1/bvn/verify');

    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 90,
        CURLOPT_POSTFIELDS     => json_encode([
            'service' => 'BVN_VALIDATION',
            'bvn'     => $bvn,
            'consent' => true,
        ]),
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('IDEX_API_KEY'),
            'Content-Type: application/json',
            'Accept: application/json',
        ],
    ]);

    $raw    = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $body = json_decode((string) $raw, true);

    // 404 means the provider answered: no such BVN. That is an answer, not an error.
    if ($status === 404) {
        return false;
    }

    if ($status !== 200 || empty($body['success'])) {
        throw new RuntimeException('BVN validation unavailable: ' . ($body['error']['code'] ?? 'network_error'));
    }

    return (bool) ($body['data']['valid'] ?? false);
}

// Server-side only.
const IDEX_KEY = process.env.IDEX_API_KEY;

async function verifyBvn(bvn, service = 'BVN_BASIC') {
  const response = await fetch('https://idex.com.ng/api/v1/bvn/verify', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${IDEX_KEY}`,
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    body: JSON.stringify({ service, bvn, consent: true })
  });

  const body = await response.json();

  // Persist the reference whenever there is one, success or not:
  // it is how the call is reconciled later.
  if (body.reference) {
    await saveReference(bvn, body.reference, body.status);
  }

  if (!response.ok || !body.success) {
    throw Object.assign(new Error(body.error?.message ?? 'BVN verification failed'), {
      code: body.error?.code ?? 'internal_error',
      requestId: body.request_id
    });
  }

  return body.data;
}

import os
import requests

BASE_URL = "https://idex.com.ng/api/v1"
API_KEY = os.environ["IDEX_API_KEY"]


def verify_bvn(bvn: str, service: str = "BVN_BASIC") -> dict:
    response = requests.post(
        f"{BASE_URL}/bvn/verify",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
            "Accept": "application/json",
        },
        json={"service": service, "bvn": bvn, "consent": True},
        timeout=90,
    )

    body = response.json()
    reference = body.get("reference")

    if reference:
        store_reference(bvn, reference, body.get("status"))

    if response.status_code == 404:
        return {"found": False, "reference": reference}

    if response.status_code != 200 or not body.get("success"):
        error = body.get("error", {})
        raise RuntimeError(f"{error.get('code', 'internal_error')}: {error.get('message', '')}")

    return {"found": True, "reference": reference, "record": body["data"]}

{
  "success": true,
  "request_id": "c40b6e19f2a74d83",
  "status": "successful",
  "reference": "IDX-260818-A19D3F04B7",
  "service": "BVN_BASIC",
  "message": "Verification completed.",
  "amount": 145.00,
  "currency": "NGN",
  "balance": 4525.50,
  "refunded": false,
  "data": {
    "bvn": "22123456789",
    "first_name": "IBRAHIM",
    "middle_name": "SANI",
    "last_name": "MUSA",
    "date_of_birth": "1988-11-02",
    "gender": "male",
    "phone_number": "08098765432",
    "nationality": "Nigeria"
  },
  "timestamp": "2026-08-18T11:22:40+01:00"
}

{
  "success": true,
  "request_id": "77e0aa3b1c5f4e26",
  "status": "successful",
  "reference": "IDX-260818-6E48B2C155",
  "service": "BVN_VALIDATION",
  "message": "Verification completed.",
  "amount": 80.00,
  "currency": "NGN",
  "balance": 4445.50,
  "refunded": false,
  "data": {
    "bvn": "22123456789",
    "valid": true
  },
  "timestamp": "2026-08-18T11:26:12+01:00"
}

# One verification by reference
curl "https://idex.com.ng/api/v1/verifications?reference=IDX-260818-4B7E1C9A02" \
  -H "Authorization: Bearer idex_live_a1b2c3d4e5f6a7b8_REPLACE_WITH_YOUR_SECRET" \
  -H "Accept: application/json"

# Everything still pending, most recent first
curl "https://idex.com.ng/api/v1/verifications?status=pending&per_page=50" \
  -H "Authorization: Bearer idex_live_a1b2c3d4e5f6a7b8_REPLACE_WITH_YOUR_SECRET" \
  -H "Accept: application/json"

{
  "success": true,
  "request_id": "e21f8b0c6d3a4917",
  "status": "ok",
  "data": {
    "reference": "IDX-260818-4B7E1C9A02",
    "service": "NIN_BASIC",
    "status": "successful",
    "channel": "api",
    "identifier": "123****8901",
    "amount": 150.00,
    "currency": "NGN",
    "refunded": false,
    "summary": "ADAEZE NGOZI OKONKWO",
    "data_available": true,
    "data": {
      "nin": "12345678901",
      "first_name": "ADAEZE",
      "last_name": "OKONKWO",
      "date_of_birth": "1991-04-17",
      "gender": "female"
    },
    "created_at": "2026-08-18T11:04:21+01:00",
    "completed_at": "2026-08-18T11:04:23+01:00"
  },
  "timestamp": "2026-08-18T12:00:00+01:00"
}

{
  "success": true,
  "request_id": "0b93de4a7c1f42a8",
  "status": "ok",
  "data": {
    "verifications": [
      {
        "reference": "IDX-260818-7C21A0FE93",
        "service": "NIN_BASIC",
        "status": "refunded",
        "identifier": "555****1234",
        "amount": 150.00,
        "refunded": true,
        "created_at": "2026-08-18T11:09:53+01:00"
      },
      {
        "reference": "IDX-260818-A19D3F04B7",
        "service": "BVN_BASIC",
        "status": "successful",
        "identifier": "221****6789",
        "amount": 145.00,
        "refunded": false,
        "created_at": "2026-08-18T11:22:38+01:00"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "pages": 4,
      "total": 68
    }
  },
  "timestamp": "2026-08-18T12:01:14+01:00"
}

curl "https://idex.com.ng/api/v1/balance" \
  -H "Authorization: Bearer idex_live_a1b2c3d4e5f6a7b8_REPLACE_WITH_YOUR_SECRET" \
  -H "Accept: application/json"

import os
import requests

BASE_URL = "https://idex.com.ng/api/v1"
LOW_WATER_MARK = 5000.00


def balance() -> float:
    response = requests.get(
        f"{BASE_URL}/balance",
        headers={
            "Authorization": f"Bearer {os.environ['IDEX_API_KEY']}",
            "Accept": "application/json",
        },
        timeout=30,
    )
    response.raise_for_status()
    return float(response.json()["data"]["balance"])


# Run this on a schedule so a verification never fails for want of funding.
if balance() < LOW_WATER_MARK:
    alert_finance_team("IDEX wallet is running low")

{
  "success": true,
  "request_id": "9f1c2d7a4b6e48f0",
  "status": "successful",
  "reference": "IDX-260818-4B7E1C9A02",
  "service": "NIN_BASIC",
  "message": "Verification completed.",
  "amount": 150.00,
  "currency": "NGN",
  "balance": 4670.50,
  "refunded": false,
  "data": {},
  "error": null,
  "timestamp": "2026-08-18T11:04:23+01:00"
}

{
  "success": false,
  "request_id": "b81f0c37e2a54d16",
  "status": "error",
  "error": {
    "code": "validation_failed",
    "message": "Please correct the highlighted fields.",
    "fields": {
      "nin": "Enter the 11-digit National Identification Number."
    }
  },
  "timestamp": "2026-08-18T11:31:09+01:00"
}

{
  "id": "evt_9a3f1c0d7b2e4856",
  "event": "verification.completed",
  "created_at": "2026-08-18T11:41:07+01:00",
  "data": {
    "reference": "IDX-260818-4B7E1C9A02",
    "service": "NIN_BASIC",
    "status": "successful",
    "previous_status": "pending",
    "identifier": "123****8901",
    "amount": 150.00,
    "currency": "NGN",
    "refunded": false,
    "completed_at": "2026-08-18T11:41:05+01:00"
  }
}

<?php

/**
 * IDEX webhook receiver.
 * Point your dashboard webhook URL at this file.
 */

$secret = (string) getenv('IDEX_WEBHOOK_SECRET');   // from Dashboard > Settings
$raw    = (string) file_get_contents('php://input');
$given  = (string) ($_SERVER['HTTP_X_IDEX_SIGNATURE'] ?? '');
$sentAt = (int) ($_SERVER['HTTP_X_IDEX_TIMESTAMP'] ?? 0);

// 1. Reject a replay before doing any work.
if ($sentAt === 0 || abs(time() - $sentAt) > 300) {
    http_response_code(400);
    exit;
}

// 2. Recompute the signature over the exact bytes received.
$expected = hash_hmac('sha512', $sentAt . '.' . $raw, $secret);

// 3. Constant-time comparison. Never use == here.
if ($secret === '' || !hash_equals($expected, $given)) {
    http_response_code(401);
    exit;
}

$event = json_decode($raw, true);

if (!is_array($event) || empty($event['id'])) {
    http_response_code(400);
    exit;
}

// 4. Delivery is at-least-once. Deduplicate on the event id.
if (alreadyProcessed($event['id'])) {
    http_response_code(200);
    exit;
}

// 5. Acknowledge quickly, then do the slow work out of band.
markProcessed($event['id']);
enqueue($event);

http_response_code(200);
echo 'ok';

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 24
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1786534884

{
  "success": false,
  "request_id": "6d1a94c70b8e42f3",
  "status": "error",
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry in 24 seconds."
  },
  "timestamp": "2026-08-18T11:47:36+01:00"
}

<?php

/**
 * Send a request, honouring Retry-After and backing off with jitter.
 *
 * $send must return [int $httpStatus, array $body, array $headers].
 */
function idexWithBackoff(callable $send, int $maxAttempts = 5): array
{
    $attempt = 0;

    while (true) {
        $attempt++;
        [$status, $body, $headers] = $send();

        $retryable = $status === 429 || $status === 500;

        if (!$retryable || $attempt >= $maxAttempts) {
            return [$status, $body];
        }

        // Honour the server's own instruction when it gives one.
        $wait = isset($headers['retry-after'])
            ? (float) $headers['retry-after']
            : (float) (2 ** $attempt);

        // Jitter: without it, throttled workers retry in lockstep for ever.
        $wait += random_int(0, 1000) / 1000;

        usleep((int) round($wait * 1000000));
    }
}

<?php

declare(strict_types=1);

/**
 * A complete IDEX client.
 *
 * The distinction that matters is between IdexException — a definite answer we
 * did not like — and IdexPending, which means the outcome is genuinely unknown
 * and the wallet has been debited. The first may be acted on. The second must
 * be reconciled, and must never be resubmitted.
 */

class IdexException extends RuntimeException
{
    public function __construct(
        public readonly string $errorCode,
        string $message,
        public readonly ?string $reference = null,
        public readonly ?string $requestId = null
    ) {
        parent::__construct($message);
    }
}

final class IdexPending extends IdexException {}

final class IdexClient
{
    private const BASE = 'https://idex.com.ng/api/v1';

    public function __construct(private readonly string $apiKey) {}

    public function verifyNin(string $nin, string $service = 'NIN_BASIC'): array
    {
        return $this->send('POST', '/nin/verify', [
            'service' => $service,
            'nin'     => $nin,
            'consent' => true,
        ]);
    }

    public function verifyBvn(string $bvn, string $service = 'BVN_BASIC'): array
    {
        return $this->send('POST', '/bvn/verify', [
            'service' => $service,
            'bvn'     => $bvn,
            'consent' => true,
        ]);
    }

    public function verification(string $reference): array
    {
        return $this->send('GET', '/verifications?reference=' . rawurlencode($reference));
    }

    public function balance(): float
    {
        return (float) $this->send('GET', '/balance')['data']['balance'];
    }

    private function send(string $method, string $path, ?array $payload = null, int $attempt = 1): array
    {
        $headers = [];
        $ch = curl_init(self::BASE . $path);

        curl_setopt_array($ch, [
            CURLOPT_CUSTOMREQUEST  => $method,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 90,
            CURLOPT_HTTPHEADER     => [
                'Authorization: Bearer ' . $this->apiKey,
                'Content-Type: application/json',
                'Accept: application/json',
                'User-Agent: acme-onboarding/1.4',
            ],
            CURLOPT_HEADERFUNCTION => function ($handle, string $line) use (&$headers): int {
                $parts = explode(':', $line, 2);
                if (count($parts) === 2) {
                    $headers[strtolower(trim($parts[0]))] = trim($parts[1]);
                }
                return strlen($line);
            },
        ]);

        if ($payload !== null) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
        }

        $raw       = curl_exec($ch);
        $status    = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $transport = curl_errno($ch) !== 0;
        curl_close($ch);

        // No response at all: the lookup may still have been performed upstream.
        if ($transport) {
            throw new IdexPending('provider_timeout', 'No response from IDEX. Reconcile before resubmitting.');
        }

        $body = json_decode((string) $raw, true);
        $body = is_array($body) ? $body : [];

        // 429 and 500 are the only statuses worth repeating.
        if (($status === 429 || $status === 500) && $attempt < 4) {
            $wait = (float) ($headers['retry-after'] ?? 2 ** $attempt);
            usleep((int) round(($wait + random_int(0, 750) / 1000) * 1000000));
            return $this->send($method, $path, $payload, $attempt + 1);
        }

        if ($status === 504) {
            throw new IdexPending(
                'provider_timeout',
                (string) ($body['error']['message'] ?? 'The provider did not answer in time.'),
                $body['reference']  ?? null,
                $body['request_id'] ?? null
            );
        }

        if ($status !== 200 || empty($body['success'])) {
            throw new IdexException(
                (string) ($body['error']['code'] ?? 'internal_error'),
                (string) ($body['error']['message'] ?? 'The request could not be completed.'),
                $body['reference']  ?? null,
                $body['request_id'] ?? null
            );
        }

        return $body;
    }
}

<?php

$idex = new IdexClient((string) getenv('IDEX_API_KEY'));

try {
    $result = $idex->verifyNin($applicant->nin);

    // The reference is the first thing to persist, always.
    $applicant->idex_reference = $result['reference'];
    $applicant->verified_name  = trim(
        ($result['data']['first_name'] ?? '') . ' ' . ($result['data']['last_name'] ?? '')
    );
    $applicant->status = 'verified';
    $applicant->save();

} catch (IdexPending $pending) {
    // Charged, unsettled, and an answer is coming. Queue it. Never resubmit.
    $applicant->idex_reference = $pending->reference;
    $applicant->status         = 'awaiting_verification';
    $applicant->save();

    queueReconcile($applicant->id, 60);

} catch (IdexException $error) {
    match ($error->errorCode) {
        'not_found'          => $applicant->markUnverified('No record found for that NIN'),
        'validation_failed'  => $applicant->markInvalid('That NIN is not well formed'),
        'insufficient_funds' => alertOps('IDEX wallet needs funding'),
        'service_unavailable'=> pauseOnboardingQueue('IDEX service not activated'),
        default              => logError('IDEX ' . $error->errorCode, $error->requestId),
    };
}

/**
 * Run from the queue. Idempotent, so it is safe on any schedule:
 * every minute for the first five, then every fifteen for an hour.
 */
function reconcile(IdexClient $idex, string $reference): string
{
    $record = $idex->verification($reference)['data'];

    return match ($record['status']) {
        'successful'          => storeResult($reference, $record['data'] ?? []),
        'failed', 'refunded'  => markUnverified($reference, $record['status']),
        default               => 'still_pending',
    };
}

"""A complete IDEX client: verify, back off, reconcile."""

import os
import random
import time

import requests

BASE_URL = "https://idex.com.ng/api/v1"
RETRYABLE = {429, 500}


class IdexError(RuntimeError):
    """A definite answer we did not like."""

    def __init__(self, code, message, reference=None, request_id=None):
        super().__init__(f"{code}: {message}")
        self.code = code
        self.reference = reference
        self.request_id = request_id


class IdexPending(IdexError):
    """Charged and unsettled. Reconcile — never resubmit."""


class IdexClient:
    def __init__(self, api_key: str, base_url: str = BASE_URL):
        self.base_url = base_url.rstrip("/")
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
            "Accept": "application/json",
            "User-Agent": "acme-onboarding/1.4",
        })

    def verify_nin(self, nin: str, service: str = "NIN_BASIC") -> dict:
        return self._send("POST", "/nin/verify", {"service": service, "nin": nin, "consent": True})

    def verify_bvn(self, bvn: str, service: str = "BVN_BASIC") -> dict:
        return self._send("POST", "/bvn/verify", {"service": service, "bvn": bvn, "consent": True})

    def verification(self, reference: str) -> dict:
        return self._send("GET", f"/verifications?reference={reference}")

    def balance(self) -> float:
        return float(self._send("GET", "/balance")["data"]["balance"])

    def _send(self, method: str, path: str, payload=None, attempt: int = 1) -> dict:
        try:
            response = self.session.request(
                method, f"{self.base_url}{path}", json=payload, timeout=90
            )
        except requests.RequestException as exc:
            # No response at all: the lookup may still have happened upstream.
            raise IdexPending("provider_timeout", "No response from IDEX") from exc

        if response.status_code in RETRYABLE and attempt < 4:
            wait = float(response.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait + random.uniform(0, 0.75))
            return self._send(method, path, payload, attempt + 1)

        try:
            body = response.json()
        except ValueError:
            body = {}

        if response.status_code == 504:
            raise IdexPending(
                "provider_timeout",
                "The provider did not answer in time",
                body.get("reference"),
                body.get("request_id"),
            )

        if response.status_code != 200 or not body.get("success"):
            error = body.get("error", {})
            raise IdexError(
                error.get("code", "internal_error"),
                error.get("message", "The request could not be completed."),
                body.get("reference"),
                body.get("request_id"),
            )

        return body

idex = IdexClient(os.environ["IDEX_API_KEY"])


def onboard(applicant) -> str:
    try:
        result = idex.verify_nin(applicant.nin)

    except IdexPending as pending:
        # Charged, unsettled. Queue it and reconcile; do not call again.
        applicant.idex_reference = pending.reference
        applicant.status = "awaiting_verification"
        applicant.save()
        schedule_reconcile(applicant.id, delay=60)
        return "pending"

    except IdexError as error:
        if error.code == "not_found":
            return applicant.mark_unverified("No record found for that NIN")
        if error.code == "validation_failed":
            return applicant.mark_invalid("That NIN is not well formed")
        if error.code == "insufficient_funds":
            alert_finance_team("IDEX wallet needs funding")
        raise

    # Persist the reference before anything else.
    applicant.idex_reference = result["reference"]
    record = result["data"]
    applicant.verified_name = " ".join(
        part for part in (record.get("first_name"), record.get("last_name")) if part
    )
    applicant.status = "verified"
    applicant.save()
    return "verified"


def reconcile(reference: str) -> str:
    """Idempotent. Every minute for five minutes, then every fifteen for an hour."""
    record = idex.verification(reference)["data"]

    if record["status"] == "successful":
        store_result(reference, record.get("data", {}))
        return "verified"

    if record["status"] in ("failed", "refunded"):
        mark_unverified(reference, record["status"])
        return "not_verified"

    return "still_pending"