rexedge/paystack-verification

Paystack Verification

The Verification API provides KYC tools for account resolution, validation, and card BIN lookups.

Depends on: paystack-setup for the paystackRequest helper.
Related: paystack-miscellaneous for fetching bank codes.

Endpoints

| Method | Endpoint | Description | | --- | --- | --- | | GET | /bank/resolve | Resolve account number to name | | POST | /bank/validate | Validate account ownership | | GET | /decision/bin/:bin | Resolve card BIN |

Resolve Account Number

Confirm an account belongs to the right customer. Returns the account holder's name.

| Param | Type | Required | Description | | --- | --- | --- | --- | | account_number | string | Yes | Bank account number | | bank_code | string | Yes | Bank code (from List Banks endpoint) |

const resolved = await paystackRequest<{
  account_number: string;
  account_name: string;
}>("/bank/resolve?account_number=0022728151&bank_code=063");
// resolved.data.account_name → "WES GIBBONS"

Verify Before Transfer Pattern

async function verifyAccountBeforeTransfer(
  accountNumber: string,
  bankCode: string,
  expectedName: string
) {
  const resolved = await paystackRequest<{
    account_number: string;
    account_name: string;
  }>(`/bank/resolve?account_number=${accountNumber}&bank_code=${bankCode}`);

  const resolvedName = resolved.data.account_name.toLowerCase();
  const expected = expectedName.toLowerCase();

  if (!resolvedName.includes(expected)) {
    throw new Error(
      `Account name mismatch: "${resolved.data.account_name}" does not match "${expectedName}"`
    );
  }

  return resolved.data;
}

Validate Account

Full account validation with identity document verification. Use before sending money.

| Param | Type | Required | Description | | --- | --- | --- | --- | | account_name | string | Yes | Customer's first and last name | | account_number | string | Yes | Account number | | account_type | string | Yes | personal or business | | bank_code | string | Yes | Bank code | | country_code | string | Yes | Two-letter ISO code (e.g. NG, ZA, GH) | | document_type | string | Yes | identityNumber, passportNumber, or businessRegistrationNumber | | document_number | string | No | Identity document number |

const validation = await paystackRequest<{
  verified: boolean;
  verificationMessage: string;
  accountAcceptsDebits: boolean;
  accountAcceptsCredits: boolean;
  accountHolderMatch: boolean;
  accountOpen: boolean;
}>("/bank/validate", {
  method: "POST",
  body: JSON.stringify({
    bank_code: "632005",
    country_code: "ZA",
    account_number: "0123456789",
    account_name: "Ann Bron",
    account_type: "personal",
    document_type: "identityNumber",
    document_number: "1234567890123",
  }),
});
// validation.data.verified → true
// validation.data.verificationMessage → "Account is verified successfully"

Resolve Card BIN

Get card brand, type, and issuing bank from the first 6 digits of a card number:

const card = await paystackRequest<{
  bin: string;
  brand: string;
  sub_brand: string;
  country_code: string;
  country_name: string;
  card_type: string; // "DEBIT" | "CREDIT"
  bank: string;
}>("/decision/bin/539983");
// card.data.brand → "Mastercard"
// card.data.card_type → "DEBIT"
// card.data.bank → "Guaranty Trust Bank"