Validate a Bank Account

Create Contact, Fund account and Validate Fund Account of type bank account via a single API.

POST /v1/fund_accounts/validations

Curl

curl -u <YOUR_KEY>:<YOUR_SECRET> \
-X POST https://api.razorpay.com/v1/fund_accounts/validations \
-H "Content-Type: application/json" \
-d '{
  "source_account_number": "7878780080316316", 
  "validation_type": "optimized", 
  "reference_id": "112233",
  "notes": {
    "random_key_1": "Make it so.",
    "random_key_2": "Tea. Earl Grey. Hot."
  },
  "fund_account": {
    "account_type":"bank_account", 
    "bank_account":{
        "name":"Gaurav Kumar", 
        "ifsc":"HDFC0000053", 
        "account_number":"765432123456789" 
    },
        "contact": {
            "name":"Gaurav Kumar",
            "email":"[e-mail]",
            "contact":"9123456789",
            "type":"employee",
            "reference_id":"Acme Contact ID 12345",
            "notes":{
                "notes_key_1":"Tea, Earl Grey, Hot",
                "notes_key_2":"Tea, Earl Grey... decaf."
            }
        }
    }
}'

Created

{
  "id": "fav_00000000000001",
  "entity": "fund_account.validation",
  "status": "created",
  "utr" : "123456789012",
  "validation_results": {
      "account_status": null,
      "registered_name": null,
      "details": null,
      "name_match_score": null
   },
  "status_details": {
    "description": "Validation request is created",
    "source": "internal",
    "reason": "validation_request_created"
    },
  "reference_id": "112233",
  "notes": {
      "random_key_1": "Make it so.",
      "random_key_2": "Tea. Earl Grey. Hot."
   },
  "fund_account": {
      "id": "fa_00000000000001",
      "entity": "fund_account",
      "account_type": "bank_account",
      "bank_account": {
            "name": "Gaurav Kumar",
            "bank_name": "HDFC",
            "ifsc": "HDFC0000053",
            "account_number": "765432123456789"
      },
      "active": true,
      "created_at": 1567064019,
      "contact": {
          "id": "cont_00000000000001",
          "entity": "contact",
          "name":"Gaurav Kumar",
          "email":"[e-mail]",
          "contact":"9123456789",
          "type":"employee",
          "reference_id":"Acme Contact ID 12345",
          "active": true,
          "created_at": 1567064019,
          "notes":{
          "notes_key_1":"Tea, Earl Grey, Hot",
          "notes_key_2":"Tea, Earl Grey... decaf."
          }
      }
  }
}

Use this endpoint to create contact, fund account and validate the bank account in a single API call.

Curl

curl -u <YOUR_KEY>:<YOUR_SECRET> \
-X POST https://api.razorpay.com/v1/fund_accounts/validations \
-H "Content-Type: application/json" \
-d '{
  "source_account_number": "7878780080316316", 
  "validation_type": "optimized", 
  "reference_id": "112233",
  "notes": {
    "random_key_1": "Make it so.",
    "random_key_2": "Tea. Earl Grey. Hot."
  },
  "fund_account": {
    "account_type":"bank_account", 
    "bank_account":{
        "name":"Gaurav Kumar", 
        "ifsc":"HDFC0000053", 
        "account_number":"765432123456789" 
    },
        "contact": {
            "name":"Gaurav Kumar",
            "email":"[e-mail]",
            "contact":"9123456789",
            "type":"employee",
            "reference_id":"Acme Contact ID 12345",
            "notes":{
                "notes_key_1":"Tea, Earl Grey, Hot",
                "notes_key_2":"Tea, Earl Grey... decaf."
            }
        }
    }
}'

Created

{
  "id": "fav_00000000000001",
  "entity": "fund_account.validation",
  "status": "created",
  "utr" : "123456789012",
  "validation_results": {
      "account_status": null,
      "registered_name": null,
      "details": null,
      "name_match_score": null
   },
  "status_details": {
    "description": "Validation request is created",
    "source": "internal",
    "reason": "validation_request_created"
    },
  "reference_id": "112233",
  "notes": {
      "random_key_1": "Make it so.",
      "random_key_2": "Tea. Earl Grey. Hot."
   },
  "fund_account": {
      "id": "fa_00000000000001",
      "entity": "fund_account",
      "account_type": "bank_account",
      "bank_account": {
            "name": "Gaurav Kumar",
            "bank_name": "HDFC",
            "ifsc": "HDFC0000053",
            "account_number": "765432123456789"
      },
      "active": true,
      "created_at": 1567064019,
      "contact": {
          "id": "cont_00000000000001",
          "entity": "contact",
          "name":"Gaurav Kumar",
          "email":"[e-mail]",
          "contact":"9123456789",
          "type":"employee",
          "reference_id":"Acme Contact ID 12345",
          "active": true,
          "created_at": 1567064019,
          "notes":{
          "notes_key_1":"Tea, Earl Grey, Hot",
          "notes_key_2":"Tea, Earl Grey... decaf."
          }
      }
  }
}

Request Parameters

source_account_number · string · required

The account from which money should be deducted for the account validation transaction.

validation_type · string

The chosen type of validation. Possible values:

• pennydrop: Razorpay will make a transaction for validation.
• penniless: Razorpay will validate the account without a transaction.
• optimized (default): Razorpay will decide whether the validation requires a transaction or not.

fund_account · object · required

Details of the fund account to which the payout was made.

account_type · string · required

The fund account type being created. Here it will be bank_account.

bank_account · object · required

The contact’s bank account details.

name · string

Account holder’s name. For example,Gaurav Kumar.

ifsc · string · required

Beneficiary bank IFSC. For example, HDFC0000053.

account_number · string · required

Beneficiary account number. For example, 765432123456789.

contact · object · required

Contact details to which the payout was made.

name · string · required

The contact’s name. For example, Gaurav Kumar.

email · string

The contact’s email address. For example, [e-mail].

contact · string

The contact’s phone number. For example, 9000090000.

type · string

A classification for the contact being created. For example, employee.

notes · object

Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.

reference_id · string

A user-generated reference given to the payout. Maximum length is 40 characters. For example, 112233. You can use this field to store your own transaction ID, if any.

Response Parameters

id · string

The unique identifier linked to the fund account. For example, fav_000000000001.

entity · string

Here it will be fund_account.validation.

status · string

The status of the account validation transaction. Possible values:

• created
• completed
• failed

utr · string

A 12-digit unique identifier for the successful IMPS fund account validation transaction. For example, 123456789012.

validation_results · object

Result of the validation.

account_status · string

Displays if the account is valid or not. Possible values:

• active
• invalid

registered_name · string

The name linked to the account. For example,Gaurav Kumar.

details · string

Details of the beneficiary account depending on the validation result.

name_match_score · string

A score between 0 - 100.

• 100: The name provided by you and the bank registered name are the same.
• 0: There is no match between the name provided by you and the bank registered name.
• Between 0 & 100: There is a partial match between the name provided by you and the bank registered name.

status_details · object

This parameter returns the current status of the customer’s bank account.

description · string

A description for the status. For example, Validation request is completed.

source · string

Possible values:

• gateway: Technical error at Razorpay Partner bank.
• beneficiary_bank: Technical error at beneficiary bank.
• business: Merchant action required.
• internal: Technical error at Razorpay’s server.

reason · string

The reason for the status, based on the description. For example, validation_completed.

fund_account · object

Fund account details to which the payout was made.

id · string

The unique identifier linked to the fund account. For example, fa_00000000000001.

entity · string

Here it will be fund_account.

account_type · string

The fund account type being created. Here it will either be bank_account or vpa.

bank_account · object

The contact’s bank account details.

name · string

Account holder’s name. For example,Gaurav Kumar.

bank_name · string

The contact’s bank name. For example, HDFC.

ifsc · string

Beneficiary bank IFSC. For example, HDFC0000053.

account_number · string

Beneficiary account number. For example, 765432123456789.

vpa · object

The contact’s virtual payment address (VPA) details.

address · string

The virtual payment address. For example, gaurav.kumar@exampleupi.

contact · object

Contact details to which the payout was made.

id · string

The unique identifier linked to the contact. For example, cont_00000000000001.

entity · string

The entity being created. Here, it will be contact.

name · string

The contact’s name. For example, Gaurav Kumar.

email · string

The contact’s email address. For example, [e-mail].

contact · string

The contact’s phone number. For example, 9000090000.

type · string

A classification for the contact being created. For example, employee.

reference_id · string

A user-generated reference given to the payout. Maximum length is 40 characters. For example, 112233. You can use this field to store your own transaction ID, if any.

active · boolean

Possible values of Fund Account status:

• true: active
• false: inactive

created_at · integer

Timestamp, in Unix, when the fund account was created. For example, 1543650891.

notes · object

User-entered notes for internal reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example, "note_key": "Beam me up Scotty".