Merchant KYC verification for Dubu Pay

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"

const response = await fetch('https://api.dubupay.com/api/v1/merchant/kyc/initiate', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' },
});

const { data } = await response.json();
console.log(data);

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"

const response = await fetch('https://api.dubupay.com/api/v1/merchant/kyc/session', {
  headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' },
});

const { data } = await response.json();
// data.session_url contains the link to open in a browser
console.log(data.session_url);

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"

const response = await fetch('https://api.dubupay.com/api/v1/merchant/kyc/status', {
  headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' },
});

const { data } = await response.json();
console.log(data.status); // "pending" | "approved" | "rejected"

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"

const customerId = 'cus_01HXK...';

const response = await fetch(
  `https://api.dubupay.com/api/v1/customers/${customerId}/kyc/initiate`,
  {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' },
  }
);

const { data } = await response.json();
console.log(data);

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"
  }'

const customerId = 'cus_01HXK...';

const response = await fetch(
  `https://api.dubupay.com/api/v1/customers/${customerId}/tier2-kyc/initiate`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ bvn: '12345678901' }),
  }
);

const { data } = await response.json();
console.log(data);

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

Status	Meaning
`not_started`	KYC has not been initiated
`pending`	Verification is in progress
`approved`	Identity verified successfully
`rejected`	Verification 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.

Get Started

Authentication

Core Concepts

Guides

Account & Security

Merchant KYC verification for Dubu Pay

Merchant KYC

Initiate KYC

Get a KYC session

Check KYC status

Customer KYC

Tier 1 — basic identity verification

Tier 2 — advanced verification (BVN / NIN)

KYC status reference

​Merchant KYC

​Initiate KYC

​Get a KYC session

​Check KYC status

​Customer KYC

​Tier 1 — basic identity verification

​Tier 2 — advanced verification (BVN / NIN)

​KYC status reference

Merchant KYC

Initiate KYC

Get a KYC session

Check KYC status

Customer KYC

Tier 1 — basic identity verification

Tier 2 — advanced verification (BVN / NIN)

KYC status reference