Sign in

Disbursements

Verify an account number

View as Markdown

In a nutshell

Confirm a customer's bank account details before you create a transfer recipient.

Confirm a customer's bank account details before you create a transfer recipient, so you don't send money to the wrong person or to an invalid account. Small input mistakes, such as a swapped digit or the wrong bank, are common when customers enter their own details. Checking the account turns those mistakes into a visible confirmation step instead of a failed or misdirected transfer, and the support work that follows it.

Use account validation to confirm that the account exists, is open, can receive credits, and belongs to the customer:

StageWhat to do
Collect detailsAsk for the account number, bank, account holder name, and identity or business registration number
Check bank supportFetch the banks that support validation
Validate accountValidate the account and check the returned fields
Create recipientCreate the transfer recipient
Initiate transferSend money to the verified recipient

Copy linkAccount validation

The Validate Account endpoint lets you validate both personal and business accounts. It checks if the provided customer details are correct and returns the status of the check. However, not all banks support account verification, so you need to confirm whether the customer's bank supports it.

Copy linkFetch supported banks

To confirm the banks that support account validation, make a request to the List Bank endpoint and pass the enabled_for_verification query parameter:

GETapi.paystack.co/bank

curl "https://api.paystack.co/bank?currency=ZAR&enabled_for_verification=true" \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY"
const https = require("https");

const options = {
  hostname: "api.paystack.co",
  port: 443,
  path: "/bank?currency=ZAR&enabled_for_verification=true",
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
  },
};

const req = https.request(options, (res) => {
  let data = "";
  res.on("data", (chunk) => {
    data += chunk;
  });
  res.on("end", () => {
    console.log(res.statusCode, JSON.parse(data));
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/bank?currency=ZAR&enabled_for_verification=true",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer " . getenv("PAYSTACK_SECRET_KEY"),
    "Cache-Control: no-cache",
  ),
));
$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . " " . $response;
?>
{
  "status": true,
  "message": "Banks retrieved",
  "data": [
    {
      "id": 140,
      "name": "Absa Bank Limited, South Africa",
      "slug": "absa-za",
      "code": "632005",
      "longcode": "632005",
      "gateway": null,
      "pay_with_bank": false,
      "active": true,
      "country": "South Africa",
      "currency": "ZAR",
      "type": "basa",
      "is_deleted": false,
      "createdAt": "2020-09-04T10:38:56.000Z",
      "updatedAt": null,
      "supported_types": [
        "business",
        "personal"
      ]
    },
    {
      "id": 146,
      "name": "Capitec Bank Limited",
      "slug": "capitec-bank-za",
      "code": "470010",
      "longcode": "470010",
      "gateway": null,
      "pay_with_bank": false,
      "active": true,
      "country": "South Africa",
      "currency": "ZAR",
      "type": "basa",
      "is_deleted": false,
      "createdAt": "2020-09-04T10:38:56.000Z",
      "updatedAt": null,
      "supported_types": [
        "personal"
      ]
    },
    {
      "id": 163,
      "name": "Standard Bank South Africa",
      "slug": "standard-bank-za",
      "code": "051001",
      "longcode": "051001",
      "gateway": null,
      "pay_with_bank": false,
      "active": true,
      "country": "South Africa",
      "currency": "ZAR",
      "type": "basa",
      "is_deleted": false,
      "createdAt": "2020-09-04T10:38:56.000Z",
      "updatedAt": null,
      "supported_types": [
        "business",
        "personal"
      ]
    }
  ]
}

The data object in the response contains the banks that support account validation. The supported_types field in each bank object contains an array of the account types that can be validated. Some banks only support personal accounts, while others support both personal and business accounts. If the customer's bank is returned in this response, then you can go ahead with account validation. Otherwise, account validation can be skipped.

Copy linkValidate account

To validate an account, make a POST request to the Validate Account endpoint. This endpoint can be used for both personal and business account validation with the following request parameters:

NameTypeDescription
account_nameStringCustomer's first and last name registered with their bank
account_numberStringCustomer's account number
account_typeStringOne of personal or business
bank_codeStringThe bank code of the customer's bank. You can fetch bank codes using List Bank.
country_codeStringThe two-digit ISO code of the customer's bank
document_typeStringCustomer's mode of identity. One of identityNumber, passportNumber, or businessRegistrationNumber
document_numberStringCustomer's identity document number

When validating a personal account number, the customer can either provide their passport or identity number. You can specify the mode of identity by passing either identityNumber or passportNumber as the document_type parameter.

For business account validation, the document_type should be businessRegistrationNumber.

POSTapi.paystack.co/bank/validate

curl https://api.paystack.co/bank/validate \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_code": "632005",
    "country_code": "ZA",
    "account_number": "0123456789",
    "account_name": "Ann Bron",
    "account_type": "personal",
    "document_type": "identityNumber",
    "document_number": "1234567890123"
  }' \
  -X POST
const https = require("https");

const params = JSON.stringify({
  "bank_code": "632005",
  "country_code": "ZA",
  "account_number": "0123456789",
  "account_name": "Ann Bron",
  "account_type": "personal",
  "document_type": "identityNumber",
  "document_number": "1234567890123"
});

const options = {
  hostname: "api.paystack.co",
  port: 443,
  path: "/bank/validate",
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
};

const req = https.request(options, (res) => {
  let data = "";
  res.on("data", (chunk) => {
    data += chunk;
  });
  res.on("end", () => {
    console.log(res.statusCode, JSON.parse(data));
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.write(params);
req.end();
<?php
$fields = [
  "bank_code" => "632005",
  "country_code" => "ZA",
  "account_number" => "0123456789",
  "account_name" => "Ann Bron",
  "account_type" => "personal",
  "document_type" => "identityNumber",
  "document_number" => "1234567890123",
];

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/bank/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode($fields),
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer " . getenv("PAYSTACK_SECRET_KEY"),
    "Content-Type: application/json",
    "Cache-Control: no-cache",
  ),
));
$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . " " . $response;
?>
{
  "status": true,
  "message": "Personal Account Verification attempted",
  "data": {
    "accountAcceptsDebits": true,
    "accountAcceptsCredits": true,
    "accountHolderMatch": true,
    "accountOpenForMoreThanThreeMonths": true,
    "accountOpen": true,
    "verified": true,
    "verificationMessage": "Account is verified successfully"
  }
}

The response contains fields that describe the account capabilities and the validation status. Use these fields to determine whether the account meets your expectations.

NameTypeDescription
accountAcceptsDebitsbooleanIndicates that the account can accept debit orders
accountAcceptsCreditsbooleanIndicates that the account can accept credits. This is useful when you want to use Transfers.
accountOpenForMoreThanThreeMonthsbooleanIndicates that the bank account has been open for more than three months
accountHolderMatchbooleanIndicates that the account holder details match the provided identity number or business registration number
accountOpenbooleanIndicates that the account is still open and functional. Dormant accounts can cause debit orders or transfers to fail.

Pricing

This endpoint costs ZAR 3 per successful request regardless of the account validation status.

Was this page helpful?