paystack-verification

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paystack Verification

Paystack验证

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.

Verification API 提供用于账户解析、验证以及卡BIN查询的KYC工具。

依赖：需通过paystack-setup获取
paystackRequest
辅助工具。
相关工具：paystack-miscellaneous用于获取银行代码。

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

方法	端点	描述
GET	`/bank/resolve`	解析账号对应的姓名
POST	`/bank/validate`	验证账户所有权
GET	`/decision/bin/:bin`	解析卡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)

typescript

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

确认账户是否属于目标客户。返回账户持有人的姓名。

参数	类型	是否必填	描述
`account_number`	string	是	银行账号
`bank_code`	string	是	银行代码（来自银行列表端点）

typescript

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

转账前验证模式

typescript

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;
}

typescript

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

typescript

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"

结合身份证件验证的完整账户验证。建议在转账前使用。

参数	类型	是否必填	描述
`account_name`	string	是	客户的全名
`account_number`	string	是	银行账号
`account_type`	string	是	`personal` （个人）或 `business` （企业）
`bank_code`	string	是	银行代码
`country_code`	string	是	两位ISO代码（例如 `NG` 、 `ZA` 、 `GH` ）
`document_type`	string	是	`identityNumber` （身份证号）、 `passportNumber` （护照号）或 `businessRegistrationNumber` （企业注册号）
`document_number`	string	否	身份证件号码

typescript

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

解析卡BIN

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

typescript

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"

通过卡号的前6位数字获取卡品牌、类型以及发卡行信息：

typescript

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"