BVN verification

Availability

BVN appears as KYC → BVN only when the active license includes the KYC Module and BVN Sub-module. Execution additionally requires a supported BVN service in the installed OneView version and an active vendor connection.

OneView supports these Prembly BVN services when they are available to the installation:

A service appears only when the installed version includes it, it has been published for the installation, and the license includes KYC with the BVN Sub-module. An older installation may need a software update and license refresh before a newly released service appears.

Before integration

1. Confirm the installed OneView release lists the required Prembly → BVN Basic or Prembly → BVN Advanced service.
2. Obtain the Prembly API secret key through the client's approved provider account and secret-management process.
3. Create a Prembly BVN sandbox connection and enter the value in Prembly API Secret Key.
4. Make the connection preferred for the sandbox environment.
5. Run only Prembly-approved test data while validating the integration.
6. Configure a preferred production connection only after provider approval and outbound access to api.prembly.com.

Saving a connection checks that the required details were supplied. It does not prove that the Prembly account, provider permissions, balance, or outbound network path are ready for a live verification.

Run a verification from the dashboard

1. Open KYC → BVN. Its canonical dashboard address is /app/kyc/bvn.
2. Select New Verification.
3. Choose an active Prembly BVN Basic or BVN Advanced connection.
4. Optionally enter a safe operational purpose.
5. Enter the BVN as an 11-digit string.
6. Select Run verification and review the normalized result in the same drawer.

Review a stored BVN result

verifications:read provides a metadata-only BVN history table. It shows the shortened reference, outcome, vendor service, and completion time without revealing names, photos, result fields, or verification details.

An authorised reviewer also needs verifications:results:read, shown as View verification results in the Roles interface. The BVN table then becomes person-focused: each row shows the supported normalized portrait, first name, last name, state of origin, and gender when the selected service returned those fields. A placeholder means the field was not available in the stored normalized result; it does not mean that the identity value is empty at the provider.

Select a row to open Verification details. BVN opens on Result, where the subject's normalized name and supported photo appear above the available labelled result fields. Use Request to review the safe request context, including purpose, vendor service, environment, adapter version, and timestamps. The drawer does not reveal the submitted BVN or raw provider request.

Use search, outcome filtering, Refresh, and Previous or Next as described in Verification history. BVN result photos and identity fields are personal data. Do not copy them into logs, tickets, screenshots, or chat.

OneView records authorised table-preview access and detail views per verification, and records denied attempts to reveal a result. Activity events never include the result fields, photo, submitted BVN, or other identity data.

Prembly BVN API request

Call the stable OneView endpoint rather than the Prembly endpoint directly:

POST /api/verifications/bvn
Authorization: Bearer <oneview-service-account-api-key>
Idempotency-Key: customer-check:00000001
Content-Type: application/json

{
  "connectionId": "<prembly-bvn-sandbox-connection-id>",
  "data": {
    "number": "<11-digit-bvn>"
  }
}

The example includes the optional Idempotency-Key because it is recommended for network retry safety. Omitting it always creates a fresh Prembly request.

Purpose is optional and is omitted from this example. When the client needs to record one, add a safe operational value such as "purpose": "Approved customer onboarding identity check". A blank or omitted purpose records no purpose. Never put the BVN or other identity data in it.

Both Prembly BVN services accept the same verification field:

Do not send the BVN as a JSON number because that can remove leading zeroes. Do not place it in the URL, Idempotency-Key, purpose, logs, metrics, screenshots, or support messages.

The selected connectionId determines whether OneView uses BVN Basic or BVN Advanced. The response is returned synchronously. This example keeps the service-specific normalized result generic because the fields available to the client depend on the selected released service:

{
  "status": true,
  "message": "Verification completed",
  "data": {
    "verification": {
      "id": "<verification-id>",
      "moduleKey": "kyc",
      "subModuleKey": "bvn",
      "status": "verified",
      "result": {
        "<normalized-field>": "<provider-approved-synthetic-value>"
      },
      "createdAt": "<iso-8601-timestamp>",
      "completedAt": "<iso-8601-timestamp>"
    }
  }
}

The normalized result may contain personal data. Do not log or share the complete response.

BVN Basic outcomes

For BVN Basic, Prembly can return provider-specific response codes inside HTTP 200. OneView maps the currently supported codes as follows:

A verified result may contain firstName, middleName, lastName, dateOfBirth, and phoneNumber. BVN Advanced can return a broader normalized identity result where the released adapter supports it. Treat every returned field as personal data and expose it only through authorised OneView access.

When a request supplies a non-blank purpose, the response includes it. Failed verifications include a non-null safe errorCode; successful outcomes omit it. result and completedAt are also omitted when they are not meaningful.

OneView does not automatically retry Prembly BVN verifications. The operation may be chargeable, and the published contract does not guarantee that a fresh provider request is safe to replay. Reusing the same OneView Idempotency-Key with the exact same connection, normalized purpose, and data returns the earlier result without another Prembly call. An absent purpose and a supplied purpose are different requests. Adding, removing, or changing purpose—or changing the connection or data—while reusing the key is rejected with an HTTP 409 conflict.

Data handling

Use the minimum subject data required by the released adapter. Never place BVN values or provider secrets in idempotency keys, logs, URLs, or support requests.

See Synchronous API for authentication, permission, purpose, idempotency, response, and safe-error details.