Building a KYC Flow on Paystack Identity APIs

Traditional KYC forces users to verify everything upfront before they can do anything. Progressive KYC lets users start using your product immediately and only asks for more verification when they need to do more.

Tier 1: Email and phone. The user signs up with an email address and phone number. You verify both (email link, SMS OTP). This is enough for browsing, saving items, and basic interactions. This tier does not use Paystack at all.

Tier 2: Bank account verification. When the user wants to receive payouts or link a bank account, you use Paystack Resolve Account Number to confirm they own the account they claim. This unlocks withdrawals up to a limit you define.

Tier 3: Identity verification. When the user wants higher limits or access to premium features, you use Paystack BVN verification to confirm their legal identity. This unlocks the highest transaction limits.

Each tier adds friction, so each tier should unlock something valuable. Users accept verification when they understand what it gives them.

Track each user's verification state in a dedicated table.

-- kyc_verifications table
CREATE TABLE kyc_verifications (
  id SERIAL PRIMARY KEY,
  user_id INTEGER NOT NULL REFERENCES users(id),
  tier INTEGER NOT NULL DEFAULT 1,
  email_verified BOOLEAN NOT NULL DEFAULT false,
  email_verified_at TIMESTAMP,
  phone_verified BOOLEAN NOT NULL DEFAULT false,
  phone_verified_at TIMESTAMP,
  bank_verified BOOLEAN NOT NULL DEFAULT false,
  bank_account_number TEXT,
  bank_code TEXT,
  bank_account_name TEXT,
  bank_verified_at TIMESTAMP,
  bvn_verified BOOLEAN NOT NULL DEFAULT false,
  bvn_verified_at TIMESTAMP,
  paystack_customer_code TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE(user_id)
);

-- Tier limits table
CREATE TABLE kyc_tier_limits (
  tier INTEGER PRIMARY KEY,
  max_per_transaction BIGINT NOT NULL,
  max_daily BIGINT NOT NULL,
  max_monthly BIGINT NOT NULL,
  description TEXT
);

INSERT INTO kyc_tier_limits (tier, max_per_transaction, max_daily, max_monthly, description) VALUES
(1, 0, 0, 0, 'No payouts - email and phone only'),
(2, 5000000, 20000000, 100000000, 'Bank verified - standard limits'),
(3, 50000000, 200000000, 1000000000, 'BVN verified - premium limits');

Amounts are in kobo. 5000000 kobo = 50,000 NGN. Adjust the limits to match your product and risk appetite.

Why a separate table: Keeping verification state separate from the users table lets you query verification status efficiently, add new verification types without altering the users table, and maintain a clean audit trail.

When a user wants to add a bank account for payouts, run Resolve Account Number and name matching.

// tier-two-verify.js
const axios = require('axios');

async function verifyBankAccount(userId, accountNumber, bankCode, userName) {
  // Step 1: Resolve the account
  var response = await axios.get(
    'https://api.paystack.co/bank/resolve',
    {
      params: { account_number: accountNumber, bank_code: bankCode },
      headers: {
        Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY,
      },
      timeout: 15000,
    }
  );

  var resolvedName = response.data.data.account_name;

  // Step 2: Compare names
  var nameResult = compareNames(userName, resolvedName);

  // Step 3: Store result and update tier
  if (nameResult.passes) {
    await db.query(
      'UPDATE kyc_verifications SET ' +
      'bank_verified = true, bank_account_number = $1, bank_code = $2, ' +
      'bank_account_name = $3, bank_verified_at = NOW(), tier = 2, updated_at = NOW() ' +
      'WHERE user_id = $4',
      [accountNumber, bankCode, resolvedName, userId]
    );
  }

  return {
    resolved_name: resolvedName,
    name_match: nameResult,
    verified: nameResult.passes,
  };
}

What to show the user: After resolution, display the resolved name: "This account is registered to OKAFOR JOHN DOE. Confirm this is your account." If the name match is close but not exact, let the user confirm manually.

What to do on failure: If the account does not resolve (422), tell the user the account was not found. If the name does not match at all, tell the user the account name does not match their profile. Let them try a different account or update their profile name.

When a user needs higher limits, prompt them to complete BVN verification.

// tier-three-verify.js
async function initiateBvnVerification(userId) {
  // Get user and their Paystack customer code
  var user = await db.query(
    'SELECT u.first_name, u.last_name, u.email, k.paystack_customer_code, ' +
    'k.bank_account_number, k.bank_code ' +
    'FROM users u JOIN kyc_verifications k ON u.id = k.user_id ' +
    'WHERE u.id = $1',
    [userId]
  );

  var userData = user.rows[0];

  // Create Paystack customer if not exists
  var customerCode = userData.paystack_customer_code;
  if (!customerCode) {
    var customer = await createPaystackCustomer(
      userData.email,
      userData.first_name,
      userData.last_name
    );
    customerCode = customer.customer_code;

    await db.query(
      'UPDATE kyc_verifications SET paystack_customer_code = $1 WHERE user_id = $2',
      [customerCode, userId]
    );
  }

  // Submit BVN verification (result comes via webhook)
  return { customerCode: customerCode, status: 'verification_submitted' };
}

// Webhook handler for BVN result
async function handleBvnWebhook(event) {
  if (event.event === 'customeridentification.success') {
    var customerCode = event.data.customer_code;
    await db.query(
      'UPDATE kyc_verifications SET ' +
      'bvn_verified = true, bvn_verified_at = NOW(), tier = 3, updated_at = NOW() ' +
      'WHERE paystack_customer_code = $1',
      [customerCode]
    );
  }
}

Ask for the BVN in a separate, focused screen. Do not bury the BVN input in a long form. Show a dedicated page that explains what BVN is, why you need it, and that you will not store the number itself. A "Why do I need to do this?" expandable section helps.

For the full BVN implementation, see the BVN verification guide.

Every time a user requests a payout, check their tier and enforce the corresponding limits.

// check-kyc-limits.js
async function canUserPayout(userId, amount) {
  var kyc = await db.query(
    'SELECT k.tier, l.max_per_transaction, l.max_daily, l.max_monthly ' +
    'FROM kyc_verifications k JOIN kyc_tier_limits l ON k.tier = l.tier ' +
    'WHERE k.user_id = $1',
    [userId]
  );

  if (kyc.rows.length === 0) {
    return { allowed: false, reason: 'KYC not initialized' };
  }

  var limits = kyc.rows[0];

  if (amount > limits.max_per_transaction) {
    return {
      allowed: false,
      reason: 'Exceeds per-transaction limit for your verification level',
      upgrade_to: limits.tier + 1,
    };
  }

  // Check daily total
  var dailyTotal = await db.query(
    'SELECT COALESCE(SUM(amount), 0) as total FROM payouts ' +
    'WHERE user_id = $1 AND status = $2 AND created_at > NOW() - INTERVAL '24 hours'',
    [userId, 'completed']
  );

  if (parseInt(dailyTotal.rows[0].total) + amount > limits.max_daily) {
    return {
      allowed: false,
      reason: 'Would exceed daily limit for your verification level',
      upgrade_to: limits.tier + 1,
    };
  }

  return { allowed: true };
}

When a limit is hit, suggest upgrading. Do not just say "limit exceeded." Say "Your current verification level allows payouts up to [amount]. Complete bank verification to increase your limit." Link directly to the verification page.

Before calling any Paystack identity API, you need the user's informed consent. This is not just good practice; the Kenya Data Protection Act and Nigeria NDPR require it.

What consent looks like in practice:

• A clear statement of what data you are verifying and why.
• An explicit action by the user (clicking "Verify my account" or "Submit for verification").
• A link to your privacy policy showing how verification data is stored and used.

What consent does not look like:

• Running identity checks silently in the background without telling the user.
• Burying consent in terms-of-service fine print.
• Pre-checked consent checkboxes.

// log-consent.js
async function logVerificationConsent(userId, verificationType) {
  await db.query(
    'INSERT INTO verification_consent_log ' +
    '(user_id, verification_type, consented_at, ip_address) ' +
    'VALUES ($1, $2, NOW(), $3)',
    [userId, verificationType, requestIpAddress]
  );
}

For detailed guidance on data protection, see the Kenya DPA guide and the Nigeria NDPR guide.

The UX of your KYC flow directly affects completion rates. Bad UX means users abandon verification and cannot use your product fully.

Show progress. Display which tier the user has reached and what each remaining tier unlocks. A simple progress bar with labels works well.

Explain the benefit at each step. "Verify your bank account to start receiving payouts." "Complete identity verification to increase your daily limit to [amount]." Benefits, not obligations.

Handle errors without panic. "We could not verify your account right now. This usually means the bank system is temporarily busy. Try again in a few minutes." Not "VERIFICATION FAILED."

One step at a time. Do not show all three tiers on a single screen with a giant form. Show only the next step the user needs to complete. After they complete it, celebrate the success and explain what they unlocked.

Let users skip and come back. If a user is not ready to verify their bank account yet, let them continue using the product at Tier 1 limits. Prompt them again when they try to do something that requires Tier 2.