Identity

The Verify Identity API allows you to confirm the authenticity of a customer’s BVN, NIN, or CAC details.
Identity verification ensures compliance with KYC (Know Your Customer) and AML (Anti-Money Laundering) requirements before enabling full financial operations.

🚀 Overview

Verify individuals using BVN or NIN.
Verify businesses using CAC.
Instantly update the customer’s verification status.
Get webhook events when verification succeeds or fails.

💡 Verifications are typically processed in real time (usually under 10 seconds).

🧍 Initiate Individual Verification (BVN or NIN)

Endpoint

POST /customers/identity/initiate

Description

Verifies an individual customer using BVN or NIN.

Request Body

{
  "type": "bvn", // bvn or nin
  "number": "12345678901",
  "customer_id": "" // optional
}

Example Request

curl -X POST "https://sandbox.tsara.ng/v1/customers/identity/initiate" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "bvn",
  "number": "12345678901",
  "customer_id": "" // optional
}'

Response

{
  "success": true,
 	"message": "Otp sent successfully",
  "data": {
    "type": "BVN",
    "number": "12345678901",
	}
}

🏢 Validate Individual Verification

Endpoint

POST /customers/identity/validate

Request Body

{
    "type": "bvn",
    "number": "12345678901",
    "otp": "123456",
}

Example Request

curl -X POST "https://sandbox.tsara.ng/v1/customers/identity/validate" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bvn",
    "number": "12345678901",
    "otp": "123456",
}'

Response

{
  "success": true,
  "message": "record fetched successfully",
    "data": {
      "bvn": "12345678901",
      "firstName": "John",
      "middleName": null,
      "lastName": "Do",
      "dateOfBirth": "1993-06-12",
      "phoneNumber1": "...",
      "phoneNumber2": "...",
      "gender": "Male",
      "email": "...",
      "lgaOfOrigin": null,
      "maritalStatus": null,
      "nin": null,
      "stateOfOrigin": "...",
      "levelOfAccount": "",
      "registrationDate": null,
      "imageBase64": "..."
  }
}

🔔 Webhook Events

Tsara sends webhook notifications for every verification attempt.

Event Type	Description
customer.verified	Customer verification succeeded.
customer.verification_failed	Customer verification failed.

Example Payload

{
  "id": "evt_303",
  "type": "customer.verified",
  "data": {
    "customer_id": "cus_123",
    "verification_type": "bvn",
    "status": "verified",
    "verified_at": "2025-10-17T12:05:00Z"
  }
}

🧠 Best Practices

Always verify customers before enabling transfers or settlements.
Store verification details for compliance and audit trails.
Handle failed verifications gracefully — prompt users to retry or provide alternate documents.
Use webhook events as the source of truth for KYC status.
In sandbox mode, use mock identifiers like 12345678900 for testing.

🔗 Related Pages

Create Customer — Add a new customer to your business.
Customers Webhooks — Handle verification events.
Bank Accounts — Create or link verified customers to NGN accounts.
Webhooks & Security — Validate webhook signatures.