Account Validation

is the process of validating your contact's bank account details or virtual payment address (VPA). It is important to validate your customer's Fund account to ensure it is the account number where the user wants to receive the amount.

Fund Account Validation is possible only for RazorpayX Lite. Below is a high-level diagrammatic overview of how to validate a contact's fund account in RazorpayX.

FAV workflow from creating a contact to adding funds and validating it.

Watch Out!

This feature is not available in test mode.

Account Validation API

Watch Out!

It is mandatory to

whitelist IPs

that you use while making payouts via APIs or the request will fail.

You can try out our APIs on the Razorpay Postman Public Workspace.

Prerequisites

The process to validate a Fund account is similar to making a regular payout. To make an account validation transaction, you must:

Create a Contact
.
Create a Fund Account
for that contact using either their bank account details or VPA.
Create an account validation transaction to validate the account.

You can refer to the Request Parameters of each API for more information.

Use Cases

Account Validation States

Shown below is the life cycle of a fund account validation transaction.

Created

This state is assigned to an account validation transaction after Razorpay receives the API request. At this stage, we are awaiting a response from the beneficiary's bank. The account details have not been validated. We do not recommend making payouts to the account while the account validation transaction is still in this status.

Completed

This state indicates that the account validation transaction was completed.

Watch Out!

The completed status does not mean the bank account or VPA is valid. It just means the account validation transaction was completed and results are available to you via the API response and webhooks payloads. Based on the response, you can decide if you should make a payout to the account.

Failed

This state indicates that the account validation transaction has failed due to a technical error.

Account Validation Entity

The Account Validation entity has the following fields:

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

entity

string The entity being created. Here, it will be fund_account.validation.

fund_account

Details of the fund account being validated.

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

entity

string The entity being created. Here, it will be fund_account.

contact_id

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

account_type

string The type of fund account linked to the contact. Here, it will 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.

username

string The username portion of the virtual payment address. For example, gaurav.kumar.

handle

string The handle portion of the virtual payment address. For example, exampleupi.

address

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

batch_id

string This parameter is populated if the fund account was created as part of a bulk upload. For example, batch_00000000000001.

active

boolean Possible values of Fund Account status, that is, if the

Fund Account is active or deactivated

true (default): active
false: inactive

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”.

created_at

integer Timestamp, in Unix, when the contact was created. For example, 1567064019.

status

string The status of the account validation transaction. Possible values:

created
completed
failed

amount

integer The amount, in paise, to be transferred as part of the account validation transaction.

Handy Tips
The value passed here does not include fees and tax. Fees and tax, if any, are deducted from your account balance.

currency

string The currency for the transfer. The value has to be INR. If no value is passed, it is assumed to be INR.

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”.

results

Results of the account validation transaction. These fields are populated when the account validation transaction moves to the completed state.

account_status

string Possible values:

active
inactive
invalid

registered_name

Account holder's name as registered with the bank.

created_at

integer Timestamp, in Unix, when the contact was created. For example, 1547566278.

utr

string The unique transaction reference. This serves as a reference that the transaction was successfully completed. For example, XXXXR7310682908954385XX.

{
  "id": "fav_00000000000001",
  "entity": "fund_account.validation",
  "fund_account": {
    "id": "fa_00000000000001",
    "entity": "fund_account",
    "contact_id": "cont_00000000000001",
    "account_type": "bank_account",
    "bank_account": {
      "name": "Gaurav Kumar",
      "bank_name": "HDFC",
      "ifsc": "HDFC0000053",
      "account_number": "765432123456789"
    },
    "batch_id": null,
    "active": true,
    "created_at": 1567064019
  },
  "status": "completed",
  "amount": 100,
  "currency": "INR",
  "notes": {
    "random_key_1": "Make it so.",
    "random_key_2": "Tea. Earl Grey. Hot."
  },
  "results": {
    "account_status": "active",
    "registered_name": "Gaurav Kumar"
  },
  "created_at": 1547566278,
  "utr": "XXXXR7310682908954385XX"
}

Validate a Bank Account

You can only validate the following information for a contact's bank account:

Bank Account Number: When the status of the transaction changes to completed, the bank passes on the bank account status in the API response. If the account is active, you can transfer funds to the account.
Beneficiary Validation: When the status of the transaction changes to completed, the bank passes on the name linked to the account in the API response. By comparing the name sent by the bank to the name provided by the customer, you can successfully validate if the account belongs to the same customer.
Amount Validation: If you want to perform an amount validation, transfer a random amount ranging between ₹1 and ₹2, for example, ₹1.27. Ask your contact to enter the amount received on your website. This acts as an additional check to validate that the customer has access to the account.

Create a Contact

Handy Tips

A new contact is created if any combination of the following details is unique: name, email, contact, type and reference_id.
If all the above details match the details of an existing contact, the API returns details of the existing contact.
Use the
Update Contact API
if you want to make changes to an existing contact.

Before you fire the API, ensure you have your API Key id and Key Secret readily available. You can

generate your API keys in RazorpayX

in live mode or in

test mode

from the

RazorpayX Dashboard

. You cannot use your test mode API keys to make live transactions and vice versa.

With the following endpoint, you can create a contact.

POST

/contacts

Request Parameters

name

mandatory

string The contact's name. This field is case-sensitive. A minimum of 3 characters and a maximum of 50 characters are allowed. Name cannot end with a special character, except .. Supported characters: a-z, A-Z, 0-9, space, ’ , - , _ , / , ( , ) and , .. For example, Gaurav Kumar.

optional

string The contact's email address. For example, gaurav.kumar@example.com.

contact

optional

string The contact's phone number. For example, 9123456789.

type

optional

string Maximum 40 characters. Classification for the contact being created. For example, employee. The following classifications are available by default:

vendor
customer
employee
self

Handy Tips

Additional classifications can be created via the

Dashboard

and then used in APIs. It is not possible to create new classifications via API.

reference_id

optional

string Maximum 40 characters. A user-entered reference for the contact. For example, Acme Contact ID 12345.

notes

optional

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”.

Response Parameters

Descriptions for the response parameters are present in the

Contact Entity

parameters table.

Create Fund Account

Handy Tips

A new fund account is created if any combination of the following details is unique: contact_id, bank_account.name, bank_account.ifsc and bank_account.account_number.
If all the above details match the details of an existing fund account, the API returns details of the existing fund account.
You cannot edit the details of a fund account.

Before you fire the API, ensure you have your API Key id and Key Secret readily available. You can

generate your API keys in RazorpayX

in live mode or in

test mode

from the

RazorpayX Dashboard

. You cannot use your test mode API keys to make live transactions and vice versa.

With the following endpoint, you can create a fund account of type bank_account.

POST

/fund_accounts

Request Parameters

contact_id

mandatory

string This is the unique identifier linked to a contact. For example, cont_00000000000001.

account_type

mandatory

string The account type you want to link to the contact ID. Here it is bank_account.

bank_account

mandatory

The contact's bank account details.

name

mandatory

string Account holder's name. Name must be between 3 - 120 characters. This field is case-sensitive. Name cannot end with a special character, except .. Supported characters: a-z, A-Z, 0-9, space, ’ , - , _ , / , ( , ) and , .. For example,Gaurav Kumar.

ifsc

mandatory

string Beneficiary bank IFSC. Has to be 11 characters. Unique identifier of a bank branch. For example, HDFC0000053.

account_number

mandatory

string Beneficiary account number. Between 5 and 35 characters. Supported characters: a-z, A-Z and 0-9. Beneficiary account number. For example, 765432123456789.

Response Parameters

Descriptions for the response parameters are present in the

Fund Account Entity

parameters table.

Validate Bank Account

Before you fire the API, ensure you have your API Key id and Key Secret readily available. You can

generate your API keys in RazorpayX

in live mode or in

test mode

from the

RazorpayX Dashboard

. You cannot use your test mode API keys to make live transactions and vice versa.

With the following endpoint, you can create a bank account validation transaction.

POST

/fund_accounts/validations

Request Parameters

account_number

mandatory

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

Pass your customer identifier number if you want money to be deducted from RazorpayX Lite.

fund_account

mandatory

The fund account id you want to validate.

mandatory

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

amount

mandatory

integer The amount, in paise, to be transferred. For example, pass 100 for ₹1. The default value for this parameter is 100.

Handy Tips
The value passed here does not include fees and tax. Fees and tax, if any, are deducted from your account balance.

currency

optional

string The currency for the transfer. The value has to be INR. If no value is passed, it is assumed to be INR.

notes

optional

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”.

Response Parameters

Descriptions for the response parameters are present in the

Account Validation Entity

parameters table.

Validate a VPA

Watch Out!

It is not possible to perform an amount validation for your contact's VPA.

You can only validate the following information for a contact's VPA:

Address Validation (VPA): When the status of the transaction changes to completed, the bank passes on the status of the VPA in the API response. If the VPA is active, you can transfer funds to the VPA.
Beneficiary Validation: When the status of the transaction changes to completed, the bank passes on the name linked to the VPA in the API response. By comparing the name sent by the bank to the name provided by the customer, you can successfully validate if the account belongs to the same customer.

Create a Contact

Handy Tips

A new contact is created if any combination of the following details is unique: name, email, contact, type and reference_id.
If all the above details match the details of an existing contact, the API returns details of the existing contact.
Use the
Update Contact API
if you want to make changes to an existing contact.

Before you fire the API, ensure you have your API Key id and Key Secret readily available. You can

generate your API keys in RazorpayX

in live mode or in

test mode

from the

RazorpayX Dashboard

. You cannot use your test mode API keys to make live transactions and vice versa.

With the following endpoint, you can create a contact.

POST

/contacts

Request Parameters

name

mandatory

optional

string The contact's email address. For example, gaurav.kumar@example.com.

contact

optional

string The contact's phone number. For example, 9123456789.

type

optional

string Maximum 40 characters. Classification for the contact being created. For example, employee. The following classifications are available by default:

vendor
customer
employee
self

Handy Tips

Additional classifications can be created via the

Dashboard

and then used in APIs. It is not possible to create new classifications via API.

reference_id

optional

string Maximum 40 characters. A user-entered reference for the contact. For example, Acme Contact ID 12345.

notes

optional

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”.

Response Parameters

Descriptions for the response parameters are present in the

Contact Entity

parameters table.

Create Fund Account

Watch Out!

It is not possible to perform an amount validation for your contact's VPA.

Handy Tips

A new fund account is created if any combination of the following details is unique: contact_id and vpa.address.
If all the above details match the details of an existing fund account, the API returns details of the existing fund account.
You cannot edit the details of a fund account.

Before you fire the API, ensure you have your API Key id and Key Secret readily available. You can

generate your API keys in RazorpayX

in live mode or in

test mode

from the

RazorpayX Dashboard

. You cannot use your test mode API keys to make live transactions and vice versa.

With the following endpoint, you can create a fund account of type vpa.

POST

/fund_accounts

Request Parameters

contact_id

mandatory

string This is the unique identifier linked to a contact. For example, cont_00000000000001.

account_type

mandatory

string The fund account type you want to link to the contact ID. Here it is vpa.

vpa

mandatory

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

address

mandatory

string Between 3 and 100 characters. Supported characters: a-z, A-Z, 0-9, ., - and one @. The virtual payment address. For example, gauravkumar@exampleupi.

Response Parameters

Descriptions for the response parameters are present in the

Fund Account Entity

parameters table.

Validate VPA

Watch Out!

It is not possible to perform an amount validation for your contact's VPA.

Before you fire the API, ensure you have your API Key id and Key Secret readily available. You can

generate your API keys in RazorpayX

in live mode or in

test mode

from the

RazorpayX Dashboard

. You cannot use your test mode API keys to make live transactions and vice versa.

With the following endpoint, you can create an VPA(UPI) account validation transaction.

POST

/fund_accounts/validations

Request Parameters

account_number

mandatory

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

Pass your customer identifier number if you want money to be deducted from RazorpayX Lite.

fund_account

mandatory

The fund account id you want to validate.

mandatory

string The unique identifier linked to a fund account. For example, fa_00000000000002.

notes

optional

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”.

Response Parameters

Descriptions for the response parameters are present in the

Account Validation Entity

parameters table.

Fetch all Account Validation Transactions

Before you fire the API, ensure you have your API Key id and Key Secret readily available. You can

generate your API keys in RazorpayX

in live mode or in

test mode

from the

RazorpayX Dashboard

. You cannot use your test mode API keys to make live transactions and vice versa.

With the following endpoint, you can retrieve the details of all account validation transactions you have made.

GET

/fund_accounts/validations?account_number={account number}

Path Parameter

account_number

mandatory

string The account from which you want to make the payout.
Account details can be found on the RazorpayX Dashboard. For example, 7878780080316316.

Pass your customer identifier number if you want money to be deducted from RazorpayX Lite.
Watch Out!
This is not your contact's bank account number.

Query Parameters

from

optional

integer Timestamp in Unix from when you want to fetch payouts.

optional

integer Timestamp in Unix till when you want to fetch payouts.

count

optional

integer Number of payouts to be fetched. Default value is 10. Maximum value is 100. This can be used for pagination, in combination with skip.

skip

optional

integer Numbers of payouts to be skipped. Default value is 0. This can be used for pagination, in combination with count.

Response Parameters

Descriptions for the response parameters are present in the

Account Validation Entity

parameters table.

Fetch Account Validation Transaction by ID

Before you fire the API, ensure you have your API Key id and Key Secret readily available. You can

generate your API keys in RazorpayX

in live mode or in

test mode

from the

RazorpayX Dashboard

. You cannot use your test mode API keys to make live transactions and vice versa.

With the following endpoint, you can retrieve the details of any particular account validation transaction.

GET

/fund_accounts/validations/:id

Path Parameter

mandatory

string This is the unique identifier linked to the account validation transaction. For example, fav_00000000000001.

Response Parameters

Descriptions for the response parameters are present in the

Account Validation Entity

parameters table.

Webhooks

Set up RazorpayX Webhooks

to configure and receive notifications when a specific

event

occurs. When one of these events is triggered, we send an HTTP POST

payload

in JSON to the webhook's configured URL.