Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dubupay.com/llms.txt

Use this file to discover all available pages before exploring further.

Know Your Customer (KYC) verification is a regulatory requirement that confirms the identity of your business and its principals. Completing merchant KYC raises your transaction limits beyond the default tier and is a prerequisite for issuing permanent virtual accounts to your customers. Dubu Pay uses a third-party identity verification provider, so the process is handled through a secure session rather than by uploading documents directly to the API.

​
Merchant KYC

​
Initiate KYC

Call POST /merchant/kyc/initiate to start the KYC process for your merchant account. This registers your intent to verify and prepares a session with the identity verification provider. 
curl -X POST https://api.dubupay.com/api/v1/merchant/kyc/initiate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get a KYC session

After initiating KYC, retrieve a session URL or token from GET /merchant/kyc/session. Redirect your authorized representative to this URL to complete identity verification through the provider’s interface. 
curl https://api.dubupay.com/api/v1/merchant/kyc/session \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
The session URL is time-limited. If it expires before completion, call GET /merchant/kyc/session again to get a fresh session link.

​
Check KYC status

Poll GET /merchant/kyc/status to check the outcome of your verification. You can also listen for the kyc.approved or kyc.rejected webhook events to avoid polling. 
curl https://api.dubupay.com/api/v1/merchant/kyc/status \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Customer KYC

In addition to merchant-level verification, you can verify your individual customers. Customer KYC is structured in two tiers with increasing verification requirements.

​
Tier 1 — basic identity verification

Tier 1 verifies a customer’s basic identity. It is sufficient for standard payment activity but does not enable permanent virtual accounts. 
curl -X POST https://api.dubupay.com/api/v1/customers/CUSTOMER_ID/kyc/initiate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Tier 2 — advanced verification (BVN / NIN)

Tier 2 collects a customer’s Bank Verification Number (BVN) or National Identity Number (NIN). This level of verification is required before you can issue a permanent virtual bank account to a customer. 
curl -X POST https://api.dubupay.com/api/v1/customers/CUSTOMER_ID/tier2-kyc/initiate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bvn": "12345678901"
  }'
You must complete Tier 2 KYC for a customer before issuing them a permanent virtual bank account. Attempts to create a permanent account for an unverified customer will fail.

​
KYC status reference

StatusMeaning
not_startedKYC has not been initiated
pendingVerification is in progress
approvedIdentity verified successfully
rejectedVerification failed — resubmission may be required
Use webhooks to receive real-time KYC status updates instead of polling the status endpoint. This keeps your integration responsive without unnecessary API calls.