Check Verification Status

Before your organization can transact in production, it must pass KYC/KYB verification. This guide shows you how to check the current verification status programmatically and what each status means.

Step 1 — Fetch verification status

curl --request GET \
  --url https://sandbox.api.nadapay.com/v1/organization/verification \
  --header 'x-api-key: YOUR_API_KEY'

Response:

{
  "data": {
    "status": "verified",
    "type": "kyb",
    "verified_at": "2025-01-01T00:00:00Z",
    "details": {
      "business_name": "Acme Corp",
      "country": "NG",
      "registration_number": "RC123456"
    }
  }
}

Step 2 — Understand the status values

Step 3 — Handle each status in your integration

pending

The organization has been created but no documents have been submitted. Direct the user to the NadaPay dashboard or trigger the document submission flow via the API.

📘

See KYC/KYB Requirements for the full list of required documents.

under_review

Documents have been submitted and are being reviewed. No action is required. Production reviews typically complete within 1–3 business days.

Listen for the organization.verified or organization.rejected webhook event instead of polling.

verified

The organization is cleared to transact. You can now create accounts, fund wallets, and execute transactions in production.

rejected

The verification was rejected. Fetch the rejection reason and address it before resubmitting:

curl --request GET \
  --url https://api.nadapay.com/v1/organization/verification \
  --header 'x-api-key: YOUR_API_KEY'

The response will include a rejection_reason field explaining what failed. Resubmit the corrected documents via the dashboard or API.

suspended

Operations are paused. Contact your NadaPay account manager directly — this cannot be resolved via the API.

Step 4 — Listen for the verification webhook

Rather than polling the verification endpoint repeatedly, configure a webhook to be notified the moment the status changes:

Organization verified:

{
  "event": "organization.verified",
  "data": {
    "organization_id": "org_01HXXXXXXXXXXXXXXXXXX",
    "status": "verified",
    "verified_at": "2025-01-01T00:00:00Z"
  }
}

Organization rejected:

{
  "event": "organization.rejected",
  "data": {
    "organization_id": "org_01HXXXXXXXXXXXXXXXXXX",
    "status": "rejected",
    "rejection_reason": "Director ID document is expired.",
    "rejected_at": "2025-01-01T00:00:00Z"
  }
}

📘

See Handling Webhooks for how to set up and verify webhook delivery.

Sandbox behaviour

In the sandbox, all organizations are automatically set to verified immediately after creation. The organization.verified webhook is also fired automatically so you can test your webhook handler end to end.

You do not need to submit any documents in the sandbox.

What's next