Api

X

Account Validation

Account Validation

Overview of Account Validation for RazorpayX, APIs and webhook payload. Validate a customer's bank account before you make payouts.

Account validation is the process of validating your contact's bank account details or virtual payment address (VPA).

Watch Out!
This feature is not available in test mode.

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

Run in Postman

Workflow🔗

Below is a high-level diagrammatic overview of how to validate a contact's fund account in RazorpayX.

Fund Account Validation Transaction Workflow

The process to validate a fund account is similar to making a regular payout.

  1. Create a contact.
  2. Create a fund account using the bank account details or VPA you want to validate.
  3. Create an account validation transaction to validate the account.

Account Validation States🔗

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

Fund Account Validation Transaction States

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.

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🔗

Use the below endpoint to create a contact:

/contacts

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.

Request Parameters🔗

namemandatory
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.
emailoptional
string The contact's email address. For example, gaurav.kumar@example.com.
contactoptional
string The contact's phone number. For example, 9123456789.
typeoptional
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_idoptional
string Maximum 40 characters. A user-entered reference for the contact. For example, Acme Contact ID 12345.
notesoptional
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🔗

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.
contact
string The contact's phone number. For example, 9123456789.
email
string The contact's email address. For example, gaurav.kumar@example.com.
type
string A classification for the contact being created. For example, employee.
reference_id
string A user-entered reference for the contact. For example, Acme Contact ID 12345.
batch_id
string This parameter is populated if the contact was created as part of a bulk upload. For example, batch_00000000000001.
active
boolean Possible values:
  • 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, 1545320320.

Create Fund Account🔗

Use the below endpoint to create a fund account of type bank_account.

/fund_accounts

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.

Request Parameters🔗

contact_idmandatory

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

account_typemandatory

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

bank_account

The contact's bank account details.

namemandatory
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.
ifscmandatory
string Beneficiary bank IFSC. Has to be 11 characters. Unique identifier of a bank branch. For example, HDFC0000053.
account_numbermandatory
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🔗

id

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

entity

string Here it will be fund_account.

contact_id

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

account_type

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

bank_account

The contact's bank account details.

ifsc
string Beneficiary bank IFSC. For example, HDFC0000053.
bank_name
string The contact's bank name. For example, HDFC.
name
string Account holder's name. For example,Gaurav Kumar.
account_number
string Beneficiary account number. For example, 765432123456789.
active

boolean Possible values:

  • true: active
  • false: inactive
batch_id

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

created_at

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

Validate Bank Account🔗

Account validation transactions can only be created via APIs.

Use the below endpoint to create an account validation transaction.

/fund_accounts/validations

Request Parameters🔗

account_number mandatory

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

  • Pass your virtual account number if you want money to be deducted from your virtual account.
fund_account

The fund account id you want to validate.

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

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.

currencyoptional

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

notesoptional

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🔗

id

string The unique identifier linked to the account validation transaction. 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.

id

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 being created. Here, it will be bank_account.

bank_account

The contact's bank account details.

ifsc
string Unique identifier of a bank branch. For example, HDFC0000053.
bank_name
string The bank name. For example, HDFC.
name
string Name of the account holder as per bank records. For example,Gaurav Kumar.
account_number
string Beneficiary account number. For example, 765432123456789.
active

boolean The fund account status. Possible values:

  • true: active
  • false: inactive
batch_id

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

created_at

integer. Timestamp in Unix when the account validation transaction was created. For example, 1545320320.

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 populate when the account validation transaction moves to the completed state.

account_status
string Possible values:
  • active
  • inactive
  • invalid
registered_name
string The name linked to the account.
created_at

integer Timestamp in Unix when the account validation transaction was created. For example, 1545320320.

utr

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

Validate a VPA🔗

Watch Out!
Currently, 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🔗

Use the below endpoint to create a contact:

/contacts

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.

Request Parameters🔗

namemandatory
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.
emailoptional
string The contact's email address. For example, gaurav.kumar@example.com.
contactoptional
string The contact's phone number. For example, 9123456789.
typeoptional
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_idoptional
string Maximum 40 characters. A user-entered reference for the contact. For example, Acme Contact ID 12345.
notesoptional
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🔗

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.
contact
string The contact's phone number. For example, 9123456789.
email
string The contact's email address. For example, gaurav.kumar@example.com.
type
string A classification for the contact being created. For example, employee.
reference_id
string A user-entered reference for the contact. For example, Acme Contact ID 12345.
batch_id
string This parameter is populated if the contact was created as part of a bulk upload. For example, batch_00000000000001.
active
boolean Possible values:
  • 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, 1545320320.

Create Fund Account🔗

Watch Out!
Currently, it is not possible to perform an amount validation for your contact's VPA.

Use the below endpoint to create a fund account of type vpa.

/fund_accounts

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.

Request Parameters🔗

contact_idmandatory

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

account_typemandatory

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

vpa

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

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

Request Parameters🔗

id

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

entity

string Here, it will be fund_account.

contact_id

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

account_type

string The fund account type being created. Here, it will be vpa.

vpa

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

boolean The status of the fund account. Possible values:

  • true: active
  • false: inactive
batch_id

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

created_at

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

Validate VPA🔗

Watch Out!
Currently, it is not possible to perform an amount validation for your contact's VPA.

Account validation transactions can only be created via APIs.

Use the below endpoint to create an account validation transaction.

/fund_accounts/validations

Request Parameters🔗

account_number mandatory

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

  • Pass your virtual account number if you want money to be deducted from your virtual account.
fund_account

The fund account id you want to validate.

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

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🔗

id

string The unique identifier linked to the account validation transaction. 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.

id

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 being created. Here, it will be vpa.

vpa

The contact's bank account details.

username
string The username for the virtual payment address. For example, gauravkumar.
handle
string The handle for the virtual payment address. For example, exampleupi.
address
string The virtual payment address. For example, gauravkumar@exampleupi.
batch_id

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

active

boolean The fund account status. Possible values:

  • true: active
  • false: inactive
created_at

integer Timestamp in Unix when the account validation transaction was created. For example, 1545320320.

status

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

  • created
  • completed
  • failed
amount

integer The transfer amount, in paise.

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
string The name linked to the account.
created_at

integer Timestamp in Unix when the account validation transaction was created. For example, 1545320320.

utr

string The unique transaction reference. This is null for VPA validation since no money is used in these transactions.

Fetch all Account Validation Transactions🔗

You can fetch details of all account validation transactions made by you via APIs.

Use the below endpoint to fetch details of all account validation transactions made by you.

/fund_accounts/validations?account_number={account number}

Path Parameters🔗

account_numbermandatory
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 virtual account number if you want money to be deducted from your virtual account.
    Watch Out!
    This is not your contact's bank account number.

Query Parameter🔗

from
integer Timestamp in Unix from when you want to fetch payouts.
to
integer Timestamp in Unix till when you want to fetch payouts.
count
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
integer Numbers of payouts to be skipped. Default value is 0. This can be used for pagination, in combination with count.

Fetch Account Validation Transaction by ID🔗

You can fetch details of an account validation transaction via API.

Use the below endpoint to fetch details of the required account validation transaction.

/fund_accounts/validations/:id

Path Parameters🔗

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

Webhooks🔗

Set Up🔗

Please read our webhook documentation for detailed information.

Available Events🔗

We support webhook notifications for the following events:

fund_account.validation.completed Bank Account and VPA
Triggered whenever an account validation transaction is completed.
fund_account.validation.failed Bank Account and VPA
Triggered whenever an account validation transaction fails.

Sample Payloads🔗

fund_account.validation.completed🔗

This webhook is triggered whenever an account validation transaction is completed.

This webhook is available for both bank account and VPA validation.

fund_account.validation.failed🔗

This webhook is triggered whenever an account validation transaction fails.

Handy Tips
This webhook is available only for bank account validation. It is not available for VPA validation.

×

ON THIS PAGE