InstantIPE Verification API

curl -X POST https://instantipe.com.ng/api/v1/ipe \
  -H "Authorization: Bearer ipe_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-request-id" \
  -d '{
         "tracking_id": "ABC1234567890"
     }'

<?php
$payload = array (
  'tracking_id' => 'ABC1234567890',
);

$ch = curl_init('https://instantipe.com.ng/api/v1/ipe');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ipe_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
        'Idempotency-Key: ' . $myOrderId,
    ],
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($res['status'] === 'success') {
    $reference = $res['data']['reference'];   // store this
} else {
    // branch on the stable code, not the message text
    match ($res['code']) {
        'insufficient_funds' => topUpWallet(),
        'duplicate_request'  => alreadySubmitted(),
        default              => logFailure($res['request_id'], $res['message']),
    };
}

const res = await fetch('https://instantipe.com.ng/api/v1/ipe', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ipe_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
    'Idempotency-Key': myOrderId,
  },
  body: JSON.stringify({
      "tracking_id": "ABC1234567890"
  }),
});

const body = await res.json();
if (body.status === 'success') {
  console.log('reference', body.data.reference);
} else {
  console.error(body.code, body.message, body.request_id);
}

import requests

res = requests.post(
    'https://instantipe.com.ng/api/v1/ipe',
    headers={
        'Authorization': 'Bearer ipe_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        'Idempotency-Key': my_order_id,
    },
    json={
        'tracking_id': 'ABC1234567890'
    },
    timeout=30,
)
body = res.json()

if body['status'] == 'success':
    reference = body['data']['reference']
else:
    raise RuntimeError(f"{body['code']}: {body['message']} ({body['request_id']})")

curl -X POST https://instantipe.com.ng/api/v1/validation \
  -H "Authorization: Bearer ipe_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-request-id" \
  -d '{
         "nin": "12345678901",
         "validation_type": "full",
         "slip_type": "standard"
     }'

<?php
$payload = array (
  'nin' => '12345678901',
  'validation_type' => 'full',
  'slip_type' => 'standard',
);

$ch = curl_init('https://instantipe.com.ng/api/v1/validation');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ipe_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
        'Idempotency-Key: ' . $myOrderId,
    ],
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($res['status'] === 'success') {
    $reference = $res['data']['reference'];   // store this
} else {
    // branch on the stable code, not the message text
    match ($res['code']) {
        'insufficient_funds' => topUpWallet(),
        'duplicate_request'  => alreadySubmitted(),
        default              => logFailure($res['request_id'], $res['message']),
    };
}

const res = await fetch('https://instantipe.com.ng/api/v1/validation', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ipe_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
    'Idempotency-Key': myOrderId,
  },
  body: JSON.stringify({
      "nin": "12345678901",
      "validation_type": "full",
      "slip_type": "standard"
  }),
});

const body = await res.json();
if (body.status === 'success') {
  console.log('reference', body.data.reference);
} else {
  console.error(body.code, body.message, body.request_id);
}

import requests

res = requests.post(
    'https://instantipe.com.ng/api/v1/validation',
    headers={
        'Authorization': 'Bearer ipe_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        'Idempotency-Key': my_order_id,
    },
    json={
        'nin': '12345678901',
        'validation_type': 'full',
        'slip_type': 'standard'
    },
    timeout=30,
)
body = res.json()

if body['status'] == 'success':
    reference = body['data']['reference']
else:
    raise RuntimeError(f"{body['code']}: {body['message']} ({body['request_id']})")

curl -X POST https://instantipe.com.ng/api/v1/nin.php \
  -H 'Authorization: Bearer ipe_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"slip_type":"NIN_STANDARD","search_value":"12345678901"}'

$ch = curl_init('https://instantipe.com.ng/api/v1/nin.php');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ipe_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['slip_type' => 'NIN_STANDARD', 'search_value' => '12345678901']),
]);
$res = json_decode(curl_exec($ch), true);
file_put_contents($res['data']['download_name'], base64_decode($res['data']['pdf_base64']));

const res = await fetch('https://instantipe.com.ng/api/v1/nin.php', {
  method: 'POST',
  headers: { Authorization: 'Bearer ipe_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 'Content-Type': 'application/json' },
  body: JSON.stringify({ slip_type: 'NIN_STANDARD', search_value: '12345678901' }),
});
const { data } = await res.json();
require('fs').writeFileSync(data.download_name, Buffer.from(data.pdf_base64, 'base64'));

<?php
$secret = 'whsec_…';                       // from the Webhooks tab
$body   = file_get_contents('php://input'); // RAW body — do not re-encode
$header = $_SERVER['HTTP_X_INSTANTIPE_SIGNATURE'] ?? '';

$t = $v1 = null;
foreach (explode(',', $header) as $part) {
    [$k, $v] = array_pad(explode('=', trim($part), 2), 2, null);
    if ($k === 't')  $t  = (int) $v;
    if ($k === 'v1') $v1 = $v;
}

if (!$t || !$v1 || abs(time() - $t) > 300) {
    http_response_code(400); exit;              // stale or malformed
}
$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
if (!hash_equals($expected, $v1)) {
    http_response_code(401); exit;              // not from InstantIPE
}

$event = json_decode($body, true);
// ... process, then acknowledge
http_response_code(200);
echo 'ok';

const crypto = require('crypto');

// mount with a RAW body parser: express.raw({ type: 'application/json' })
app.post('/hooks/instantipe', (req, res) => {
  const secret = process.env.INSTANTIPE_WEBHOOK_SECRET;
  const header = req.get('X-InstantIPE-Signature') || '';
  const parts  = Object.fromEntries(header.split(',').map(p => p.trim().split('=')));

  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.t || !parts.v1 || age > 300) return res.sendStatus(400);

  const expected = crypto.createHmac('sha256', secret)
    .update(`${parts.t}.${req.body}`).digest('hex');

  const a = Buffer.from(expected), b = Buffer.from(parts.v1);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);

  const event = JSON.parse(req.body);
  // ... process
  res.sendStatus(200);
});

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.strip().split('=', 1) for p in header.split(','))
    t, v1 = parts.get('t'), parts.get('v1')
    if not t or not v1 or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(),
        f'{t}.'.encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, v1)