User Management API
This section documents endpoints fintechs use to onboard users, verify identity, retrieve user details, and manage user status.User Management API — Endpoints Overview
| Section | Endpoint | Method | Description |
|---|---|---|---|
| Onboard User | /onboarduser | POST | Onboard a new user with BVN verification. |
| Check Onboarding Status | /onboardstatus | POST | Check the current status of a user onboarding request. |
| Get User Details | /getuserdetails | POST | Retrieve detailed information about a user account, including wallets and virtual accounts. |
| Manage User Status | /manageuserstatus | POST | Activate or deactivate a user account with a reason for status change. |
| List Fintech Users | /listfintechusers | POST | Retrieve a paginated list of all users belonging to a fintech. |
Onboard a new user with BVN verification
- Request (Onboard)
- Body (Onboard)
- Response (Onboard)
- Error (Onboard)
POST {{BASE_URL}}/onboarduser
{
"bvn": "12345678901"
}
{
"status": "Success",
"response_code": "00",
"message": "User registration initiated",
"data": {
"requestId": "7898f29e-10a6-4b2b-9496-f4ee50549fd4",
"status": "processing",
"userHash": "user_uniqueID",
"message": "User registration request has been submitted for processing",
"estimatedCompletionTime": "2-5 minutes"
}
}
{
"status": "Error",
"response_code": "01",
"message": "Validation error",
"error": "Invalid BVN format. BVN must be 11 digits"
}
{
"status": "Error",
"response_code": "01",
"message": "User already exists",
"error": "A user with this BVN is already registered"
}
{
"status": "Error",
"response_code": "05",
"message": "BVN verification failed",
"error": "Unable to verify BVN with identity provider"
}
Check the current status of a user’s onboarding request.
- Request (User Status)
- Body (User Status)
- Response (User Status)
- Error (User Status)
POST {{BASE_URL}}/onboardstatus
{
"requestId": "7898f29e-10a6-4b2b-9496-f4ee50549fd4"
}
{
"status": "Success",
"response_code": "00",
"message": "User registration completed successfully",
"data": {
"type": "user_registration",
"userId": "user_uniqueID",
"status": "completed",
"createdAt": "2026-01-18T19:33:39.945Z",
"message": "User registration completed successfully"
}
}
{
"status": "Error",
"response_code": "02",
"message": "Request not found",
"error": "No onboarding request found with the provided requestId"
}
Retrieve detailed information about a user account
- Request (Get User)
- Body (Get User)
- Response (Get User)
- Error (Get User)
POST {{BASE_URL}}/getuserdetails
{
"userId": "user_uniqueID"
}
{
"status": "Success",
"response_code": "00",
"message": "User details retrieved successfully",
"data": {
"userId": "user_uniqueID",
"isActive": true,
"personalDetails": {
"firstName": "John",
"middleName": "Doe",
"lastName": "Smith"
},
"walletDetails": {
"evmWallet": "0x2KCC051A79dE65d7068542cB5D9D03754cc22F60",
"bantuWallet": "GB63QBTTWQXRO5BNO3Z4RRAGBPQFDGAGWNHKHTGSJOZF3V2NKG7V4XTY",
"solanaWallet": "HaXjvARhAxjKZRojmer86G31kXm52Nd4FZP4jrg4H2hf",
"walletCreatedAt": "2025-08-20T10:15:00.000Z"
},
"virtualAccounts": [
{
"accountNumber": "1234567890",
"accountName": "John Doe",
"bankName": "Optimus Bank",
"bankCode": "0000",
"provider": "novac",
"accountType": "user_permanent",
"reference": "userId",
"createdAt": "2026-05-29T12:42:45.034Z"
}
]
}
}
{
"status": "Error",
"response_code": "02",
"message": "User not found",
"error": "No verified user found with the provided userId"
}
Activate or deactivate a user account
- Request (Manage User)
- Body (Manage User)
- Response (Manage User)
- Error (Manage User)
POST {{BASE_URL}}/manageuserstatus
{
"userId": "user_uniqueID",
"active": false,
"reason": "Account suspended by customer request"
}
{
"status": "Success",
"response_code": "00",
"message": "User deactivated successfully",
"data": {
"userId": "user_uniqueID",
"active": false,
"changedAt": "2025-12-16T09:17:33.658Z"
}
}
{
"status": "Error",
"response_code": "02",
"message": "User not found",
"error": "No verified user found with the provided userId"
}
{
"status": "Error",
"response_code": "01",
"message": "Validation error",
"error": "Reason is required when deactivating a user"
}
List all fintech users
- Request (List Users)
- Body (List Users)
- Response (List Users)
POST {{BASE_URL}}/listfintechusers
{
"limit": 20,
"offset": 0,
"status": "all",
"orderBy": "verifiedAt",
"orderDirection": "desc"
}
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
limit | number | No | 20 | Number of users to return (1-100) |
offset | number | No | 0 | Number of users to skip |
status | string | No | ”all” | Filter by status: “active”, “inactive”, “all” |
orderBy | string | No | ”verifiedAt” | Sort field: “createdAt” or “verifiedAt” |
orderDirection | string | No | ”desc” | Sort direction: “asc” or “desc” |
{
"status": "Success",
"response_code": "00",
"message": "Users retrieved successfully",
"data": {
"users": [
{
"userId": "abc123...",
"firstName": "John",
"lastName": "Doe",
"isActive": true,
"hasWallet": true,
"wallets": {
"evm": "0x...",
"solana": null,
"bantu": null
},
"virtualAccount": {
"accountNumber": "1234567890",
"accountName": "John Doe",
"bankName": "Fidelity Bank",
"bankCode": "070",
"provider": "redbiller"
},
"verifiedAt": "2026-05-10T12:00:00.000Z",
"createdAt": "2026-05-10T12:00:00.000Z"
}
],
"pagination": {
"total": 150,
"limit": 20,
"offset": 0,
"currentPage": 1,
"totalPages": 8,
"hasNextPage": true,
"hasPreviousPage": false
}
}
}