#Bank account verification

#What is (website name) Bank account verification API?

(website name) Bank account verification API allows you to use just one API to verify your customer's Bank account details.

We integrate with RBI licensed banks to provide bank account verification service. ₹1 is credited to the bank account that has to be verified.

#What can I do with this product?

Use our lightweight verification APIs to verify bank account information of your customer—to check identity during onboarding or to enable transfers to the account. You can choose one of the following modes to integrate with bank account verification APIs—

Sync API

Use a single verification API, with a simpler integration, and wait for success/failure response.

Async API

Initiate a verification request, and update your customer on the UI, whenever status is available.

Was this page helpful?

Reading time — 0 minutes

#API integration

The integration for our bank account verification APIs can be either sync or async. You can read more about the integration process in the sub-sections.

Sync API
Async API

Was this page helpful?

Reading time — 3 minutes

#Sync API

The following guide describes a sync API implementation for bank account verification. This lets you initiate a verification request and expect an immediate response on the status of the verification. Essentially, you will need the following API—

  • Verify bank account—This lets you initiate a verification request, and get verification status in response.

Here are the URLs you would need for this integration—

  • Sandbox—https://dg-sandbox.(website name).co
  • Production—https://dg.(website name).co
  • Headers—Contact (website name) for providing the credentials required to successfully call (website name) APIs. This contains:
    • x-client-id
    • x-client-secret
    • x-product-instance-id

While this is a simpler implementation, the experience for your end customer may be better handled with our async APIs, that let you asynchronously fetch the status associated with a bank verification request.
You can update the pending status on your UI , whenever the new status is available, rather than letting your customer wait for a response on the UI.

#Verify bank account

Call this API to verify bank account of your customer. A quick explanation of the request params—

  • ifsc is the IFSC (Indian Financial System Code) of the bank branch, where the bank account is held.
  • accountNumber is the bank account number that has to be verified.

While testing on Sandbox, you may use the following sample values—

  • Use ABCD0123456 (IFSC) and 1234567890 (account number) to get a successful verification response.
  • Use DCBA6543210 (IFSC) and 0987654321 (account number) to get a failed verification response.

Your request contains a valid bank account and (website name) has processed your request successfully.

Request
POST  /api/verify/ban 
 
{ 
  "ifsc": "CNRB0008517",  
  "accountNumber": "8517129000033" 
}
Response
{ 
  "code": "BAV00",
  "verification": "success", 
  "message": "Account exists and is active.", 
  "data": {
    "name": "name of the account holder", 
    "transactionReference": "120716373986",
    "verifiedAt": "2017-08-28T09:36:18+00:00"
  },
  "id": "d9342684-1300-4fa8-8344-cc861a20a477",
  "traceId": "..."
}

Was this page helpful?

Reading time — 4 minutes

#Async API

The following guide describes an async implementation of our bank account verification APIs. This lets you initiate a verification request and let it complete asynchronously—without having to wait for an immediate response. Essentially, you will need the following 2 APIs—

  • Verify bank account—This lets you initiate a verification request.
  • Get verification request details—This lets you check the status associated with the verification request.

Here are the URLs you would need for this integration—

  • Sandbox—https://dg-sandbox.(website name).co
  • Production—https://dg.(website name).co
  • Headers—Contact (website name) for providing the credentials required to successfully call (website name) APIs. This contains:
    • x-client-id
    • x-client-secret
    • x-product-instance-id

#Verify bank account

Call this API to initiate bank account verification of your customer. A quick explanation of the request params—

  • ifsc is the IFSC (Indian Financial System Code) of the bank branch, where the bank account is held.
  • accountNumber is the bank account number that has to be verified.
  • narration is the reason for carrying out bank account verification

While testing on Sandbox, you may use sample values to mimic real-life scenarios. Use the below values to get specific responses from the Get verification request details API.


Set the accountNumber value as 1234567890 always. Use the ifsc values as mentioned below, to mimic respective scenarios—

  • ABCD0123456—successful verification response.
  • ABCD0123457—invalid transaction response. This may happen if the provided account does not support IMPS transactions.
  • ABCD0123458—transaction limit may have been reached. This may happen if, at the time of the penny drop, the transaction breaches the the daily IMPS limit for the account. While this is rare, it is still a possibility.
  • ABCD0123459—downstream service error.
  • ABCD0123450—pending verification.
  • ABCD0123467—invalid account details.

Your request contains a valid bank account number and the verification request has been successfully initiated.

Request
POST  /api/verify/ban/async 
 
{ 
  "ifsc": "ABCD0123456",  
  "accountNumber": "1234567890", 
  "narration": "test transaction for verification" 
}
Response

You get an id associated with the verification request, which you can use to check verification status asynchronously.

{ 
  "id": "02c2dc4c-1015-4ea0-8ec4-987829fc70cc" 
}

#Get verification request details

Call this API to know verification status of request that was previously initiated, against the id associated with it.

Verification was successful and the account is active.

Request
POST  /api/verify/ban/async/:requestId
Response

You get the name of the account holder in the response.

{
  "id": "d9342684-1300-4fa8-8344-cc861a20a488",
  "code": "BAV00",
  "verification": "success", 
  "message": "Account exists and is active.", 
  "data": { 
    "name": "name of the account holder", 
    "transactionReference": "120716373986",
    "verifiedAt": "2017-08-28T09:36:18+00:00"
  } 
  "traceId": "...",
}

Was this page helpful?

Reading time — 1 minutes

#Notifications

Below is the summary of the notifications which need to be processed on your server by exposing an endpoint for (website name) to send an HTTP POST request.

These notifications are sent by (website name) when the BAV Async Penny drop request is completed and we receive a response from our Banking partner regarding the status of the penny drop request.

Please send back an HTTP 200 status code if the request sent was processed correctly to avoid receiving multiple notifications for the same async penny drop event. Response body is ignored.


The base_url is the server URL you share with us to receive notifications.

To get started quickly, you can setup a mock API endpoint using Beeceptor. Once configured, (website name) will send notifications to that URL.

This will help you understand the notification flow before you start to implement it on your server.

#Notification Samples

Here’s a sample notification of a successful penny drop request, with the corresponding request id as well as the details of the account holder.



  {
  "data": {
    "bav": {
      "id": "82ff6686-691d-4a8f-b4de-6c81354b8a17",
      "verification": "success",
      "message": "Account exists and is active.",
      "data": {
        "name": "JOHN DOE",
        "transactionReference": "307316973027",
        "verifiedAt": "2023-03-14T10:35:51+00:00",
        "matchKey": null
      }
    }
  },
  "event": "BAV_WEBHOOK_NOTIFICATION",
  "timeStamp": "2023-03-14T16:05:52.093816+05:30"
}

Here is a sample notification of a failed penny drop request, with the corresponding request id as well as the reason for failure.



  {
  "data": {
    "bav": {
      "id": "82ff6686-691d-4a8f-b4de-6c81354b8a17",
      "verification": "failed",
      "message": "This account does not exist or is invalid.",
      "data": {}
    }
  },
  "event": "BAV_WEBHOOK_NOTIFICATION",
  "timeStamp": "2023-03-14T16:43:57.561533+05:30"
}

Was this page helpful?

Data Gateway - Bank account verification

Download API definition
Base URL

https://dg-sandbox.(website name).co

Authentication

HTTP authentication - bearer

Include the API key in a header, bearer.

Example :Authorization: bearer credentials

Description

Confirm the validity of an account from the account holder’s bank, with penny-drop done in real-time.

Verify BAN

https://dg-sandbox.(website name).co/api/verify/ban

Request

Header parameters

x-client-id

string

Required

x-client-secret

string

Required

x-product-instance-id

string

Required

Body

ifsc

string

Required

accountNumber

string

Required

Response

Body

verification

string

Required

message

string

Required

Language

curl

Node

Python

Go

Request sample

curl --request POST \
  --url https://dg-sandbox.(website name).co/api/verify/ban \
  --header 'content-type: application/json' \
  --header 'x-client-id: test-client' \
  --header 'x-client-secret: 891707ee-d6cd-4744-a28d-058829e30f12' \
  --header 'x-product-instance-id: 891707ee-d6cd-4744-a28d-058829e30f10' \
  --data '{
    "ifsc": "ABCD0123456",
    "accountNumber": "1234567890"
}'
200 OK

Response sample

{
  "verification": "failed",
  "message": "This account does not exist or is invalid."
}

Verify BAN Async

https://dg-sandbox.(website name).co/api/verify/ban/async

Request

Header parameters

x-client-id

string

Required

x-client-secret

string

Required

x-product-instance-id

string

Required

Body

ifsc

string

Required

accountNumber

string

Required

narration

string

Required

Response

Body

id

string

Required

Language

curl

Node

Python

Go

Request sample

curl --request POST \
  --url https://dg-sandbox.(website name).co/api/verify/ban/async \
  --header 'content-type: application/json' \
  --header 'x-client-id: test-client' \
  --header 'x-client-secret: 891707ee-d6cd-4744-a28d-058829e30f12' \
  --header 'x-product-instance-id: 891707ee-d6cd-4744-a28d-058829e30f10' \
  --data '{
    "ifsc": "ABCD0123456",
    "accountNumber": "1234567890",
    "narration": "test transaction for verification"
}'
200 OK

Response sample

{
  "id": "02c2dc4c-1015-4ea0-8ec4-987829fc70cc"
}

Get BAV request details

https://dg-sandbox.(website name).co/api/verify/ban/async/{RequestId}

Request

Path parameters

RequestId

string

Required

Header parameters

x-client-id

string

Required

x-client-secret

string

Required

x-product-instance-id

string

Required

Response

Body

verification

string

Required

message

string

Required

Language

curl

Node

Python

Go

Request sample

curl --request GET \
  --url https://dg-sandbox.(website name).co/api/verify/ban/async/{RequestId} \
  --header 'x-client-id: test-client' \
  --header 'x-client-secret: 891707ee-d6cd-4744-a28d-058829e30f12' \
  --header 'x-product-instance-id: 891707ee-d6cd-4744-a28d-058829e30f10'
200 OK

Response sample

{
  "verification": "failed",
  "message": "This account does not exist or is invalid."
}

# Set up BAV API Integration

The following guide describes an (website name) BAV implementation of our bank account verification APIs. This lets you initiate a verification request and let it complete asynchronously—without having to wait for an immediate response and it generates webhook when bank account verification is completed.

You will need the following 2 APIs—

  • Create (website name) BAV—This lets you initiate a verification request.
  • GET (website name) BAV details—This lets you check the status associated with the verification request.

Here are the URLs you would need for this integration—

  • Sandbox—https://dg-sandbox.(website name).co
  • Production—https://dg.(website name).co
  • Headers—Contact (website name) for providing the credentials required to successfully call (website name) APIs. This contains:
    • x-client-id
    • x-client-secret
    • x-product-instance-id

# Create (website name) BAV

Call this API to initiate bank account verification of your customer. A quick explanation of the request params—

  • accountNumber is the bank account number that has to be verified.
  • ifsc is the IFSC (Indian Financial System Code) of the bank branch, where the bank account is held.

Sample account number and ifsc for Sandbox.

  • accountNumber:1234567890, ifsc:UTIB0002083 - Successful Verification Type 1 (PennyLess Drop)
  • accountNumber:1234567891, ifsc:UTIB0002083 - Successful Verification Type 2 (PennyLess Drop)
  • accountNumber:1234567895, ifsc:UTIB0002083 - Successful Verification Type 3 (Penny Drop)


Your request contains a valid bank account number and the verification request has been successfully initiated.

Request
POST  /api/verify/(website name)-bav/async
 
{ 
  "ifsc": "UTIB0002083",  
  "accountNumber": "1234567890", 
}
Response

You get an id associated with the verification request, which you can use to check verification status asynchronously.

{
    "id": "3afb7ca0-535a-4d5a-9892-960c03c4e966",
    "status": "CREATED",
    "traceId": "e99b6f9a-41bc-4063-adcf-cd27043785d4"
}

# GET (website name) BAV details

Call this API to know verification status of request that was previously initiated, against the id associated with it.

Response Type 1

In processing
Request 
GET /api/verify/(website name)-bav/:requestId
Response 
{
    "id":"3afb7ca0-535a-4d5a-9892-960c03c4e966", 
    "status": "IN_PROGRESS",
    "traceId":"e99b6f9a-41bc-4063-adcf-cd27043785d4" 
}

Response Type 2

Verification done through PennyLess Drop
Request 
GET /api/verify/(website name)-bav/:requestId
Response 
{
    "id": "50c4b0a4-7de2-4eb3-9d78-153fb4d9991d",
    "status": "SUCCESS",
    "fulfillmentType": "PENNYLESS",
    "data": {
        "bankAccountNumber": "1234567890",
        "bankAccountIfsc": "UTIB0002083",
        "bankAccountName": "PAVANKUMAR KAMAT BIZ",
        "ifscCrossCheck": true,
        "ifscDetails": { // if ifscCrossCheck is true
            "name": "Axis Bank",
            "branch": "KAPODRA, SURAT",
            "center": "SURAT",
            "district": "SURAT",
            "state": "GUJARAT",
            "address": "J R SQUARE, MAMTA PARK - 1 KAPODRA, VARACHHA MAIN ROAD,  SURAT - 395 006",
            "contact": "+919824188896",
            "imps": "true",
            "rtgs": "true",
            "city": "SURAT",
            "iso3166": "IN-GJ",
            "neft": "true",
            "micr": "395211016",
            "upi": "true",
            "swift": ""
        },
        "entityType": "MERCHANT", // or 'INDIVIDUAL'
        "merchantDetails": { // if entityType is MERCHANT
            "mccCode": "1520",
            "identifier": {
                "merchantType": "SMALL",
                "merchantGenre": "OFFLINE",
                "onBoardingType": "BANK"
            },
            "name": {
                "brand": "praimports",
                "legal": "Indian",
                "franchise": "rajababuimpor"
            },
            "ownership": {
                "type": "PRIVATE"
            }
        }
    },
    "traceId": "1ab2fbc8-5b10-4358-8a87-a46592b89a6b"
}

Response Type 3

Verification done through PennyDrop
Request
GET /api/verify/(website name)-bav/:requestId
Response
{
    "id": "3afb7ca0-535a-4d5a-9892-960c03c4e966",
    "status": "SUCCESS",
    "fulfillmentType": "PENNYDROP",
    "data": {
        // No "entityType" and "merchantDetails" in case of PennyDrop
        "bankAccountNumber": "1234567890",
        "bankAccountIfsc": "ABCD0123456",
        "bankAccountName": "Test User Name",
        "ifscCrossCheck": true,
        "ifscDetails": {
            "name": "State Bank of India",
            "branch": "CANTONMENT, BARODA",
            "center": "BARODA",
            "district": "BARODA",
            "state": "GUJARAT",
            "address": "BARODA MUNICIPAL CORPN. SHOPPING COMPLEX,NEAR FATEHGUNJ PETROL PUMP ,FATEHGUNJ BARODA ,PIN - 390002",
            "contact": "+912652795129",
            "imps": "true",
            "rtgs": "true",
            "city": "VADODARA",
            "iso3166": "IN-GJ",
            "neft": "true",
            "micr": "390002022",
            "upi": "true",
            "swift": ""
        }
    },
    "traceId": "cf7d0e36-1eb8-46b1-ac66-e0576d4d18f1"
}

#Get notified via webhook

As soon as (website name) BAV compelete (success or failed). (website name) triggers a near realtime notification via webhook mechanism. See Notifications page for more information

Was this page helpful?

# Notifications

Below is the summary of the notifications which need to be processed on your server by exposing an endpoint for (website name) to send an HTTP POST request. These notifications are sent by (website name) when the (website name) BAV request is completed

Please send back an HTTP 2xx status code if the request sent was processed correctly to avoid receiving multiple notifications for the same event. Response body is ignored.


This will help you understand the notification flow before you start to implement it on your server.

# Notification Samples

Here’s a sample notification of a successful (website name) BAV request, with the corresponding request id as well as the details of the account holder.

{
  "data": {
      "id": "50c4b0a4-7de2-4eb3-9d78-153fb4d9991d",
      "fulfillmentType": "PENNYLESS", // OR "PENNYDROP"
      "status": "SUCCESS",
      "traceId": "..."
      "data":{ 
        "bankAccountNumber": "20161854381",
        "bankAccountName" : "MR PAVANKUMAR NAGARAJ KAMAT" , 
        "bankAccountIfsc": "SBIN0015421",
        "entityType": "MERCHANT", // or "INDIVIDUAL". Note: this key will be present in case of PENNYDROP
        "ifscCrossCheck": true,
        "ifscDetails": { // if ifscCrossCheck=true
          "name": "State Bank of India",
          "branch": "SHIVAJI CHOWK, SIRSI",
          "center": "UTTAR KAKINADA",
          "district": "UTTAR KAKINADA",
          "state": "KARNATAKA",
          "address": "MAHESH PLAZA, NATARAJ ROAD, SIRSI. PIN581401 UTTARA KANNADA DIST KARNATAKA",
          "contact": "",
          "imps": "true",
          "rtgs": "true",
          "city": "SIRSI",
          "iso3166": "IN-KA",
          "neft": "true",
          "micr": "581002402",
          "upi": "true",
          "swift": ""
        }
      },
      "merchantDetails": { // if entityType is "MERCHANT"
        "mccCode": "1520",
        "identifier": {
          "merchantType": "SMALL",
          "merchantGenre": "OFFLINE",
          "onBoardingType": "BANK"
        },
        "name": {
          "brand": "praimports",
          "legal": "Indian",
          "franchise": "rajababuimpor"
        },
        "ownership": {
          "type": "PRIVATE"
        }
    }
  },
  "event": "(website name)_BAV_NOTIFICATION",
  "timeStamp": "2023-08-22T20:44:40.203527+05:30"
}

Here is a sample notification of a failed (website name) BAV request, with the corresponding request id as well as the reason for failure.



  {
  "data": {
     "id": "50c4b0a4-7de2-4eb3-9d78-153fb4d9991d",
      "error": {
          "code": "<(website name)_BAV_CODE>",
          "detail": "<(website name)_BAV_CODE_DESCRIPTION>",
          "traceId": ""
      }
  },
  "event":"(website name)_BAV_NOTIFICATION", 
  "timeStamp":"2023-08-22T20:44:40.203527+05:30" 
}

Was this page helpful?