NIN & BVN Verification API

1. Authentication

Keep the key on your backend server. Never expose it in public JavaScript, screenshots or mobile application source code.

2. NIN request

curl -X POST "https://portal.sdtopup.com.ng/api/v1/nin.php" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"nin":"12345678901","slip_type":"standard","reference":"ORDER-10001"}'

Slip types: basic, regular, standard, premium, vnin.

3. BVN request

curl -X POST "https://portal.sdtopup.com.ng/api/v1/bvn.php" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"bvn":"12345678901","slip_type":"standard","reference":"ORDER-10002"}'

4. Successful response

{
  "status": "success",
  "message": "Verification completed.",
  "reference": "NIN-20260905-ABC123",
  "client_reference": "ORDER-10001",
  "pdf_ready": true,
  "download_url": "https://portal.sdtopup.com.ng/api/v1/download.php?reference=NIN-20260905-ABC123"
}

The upstream supplier is not exposed. Save both references and the download URL.

5. Download the PDF

The download is a second authenticated request. Send the same API key:

curl "DOWNLOAD_URL_FROM_RESPONSE" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Accept: application/pdf" \
 --fail-with-body \
 --output verification-slip.pdf

A successful response has Content-Type: application/pdf. Opening the URL directly in a browser usually fails because the browser does not automatically include your API key.

6. Node.js server download

const response = await fetch(downloadUrl, {
  headers: {
    Authorization: `Bearer ${process.env.SD_API_KEY}`,
    Accept: "application/pdf"
  }
});
const type = response.headers.get("content-type") || "";
if (!response.ok || !type.includes("application/pdf")) {
  const error = await response.json();
  throw new Error(error.message || "PDF download failed");
}
const pdfBuffer = Buffer.from(await response.arrayBuffer());

7. PDF troubleshooting

1. Do not repeat a successful verification.
2. Confirm the response has status: success, pdf_ready: true and download_url.
3. Request that URL from the developer's backend with the same Bearer key.
4. Check the HTTP status and Content-Type before saving.
5. If the response is JSON, read its message; it is an error, not a PDF.
6. For a temporary download error, retry the same download URL. Never create a new verification reference.
7. Contact support with the portal and client references—never send an API key or full identity number.

Never: expose the API key in a frontend download button or repeat verification merely because downloading failed.

8. Status and billing