> ## 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.

# Merchant KYC verification for Dubu Pay

> Complete KYC verification to raise your transaction limits and unlock permanent virtual accounts for your customers on 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.dubupay.com/api/v1/merchant/kyc/initiate \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript Node.js theme={null}
  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);
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.dubupay.com/api/v1/merchant/kyc/session \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript Node.js theme={null}
  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);
  ```
</CodeGroup>

<Note>
  The session URL is time-limited. If it expires before completion, call `GET /merchant/kyc/session` again to get a fresh session link.
</Note>

### 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.dubupay.com/api/v1/merchant/kyc/status \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript Node.js theme={null}
  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"
  ```
</CodeGroup>

***

## 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.dubupay.com/api/v1/customers/CUSTOMER_ID/kyc/initiate \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript Node.js theme={null}
  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);
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  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);
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

## 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 |

<Tip>
  Use webhooks to receive real-time KYC status updates instead of polling the status endpoint. This keeps your integration responsive without unnecessary API calls.
</Tip>