Watch Out!
It is mandatory to
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.
Overview of Account Validation for RazorpayX, APIs and webhook payload. Validate a customer's bank account before you make payouts.
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.
Watch Out!
This feature is not available in test mode.
Watch Out!
It is mandatory to
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.
The process to validate a Fund account is similar to making a regular payout. To make an account validation transaction, you must:
You can refer to the Request Parameters of each API for more information.
Shown below is the life cycle of a fund account validation transaction.
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.
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.
This state indicates that the account validation transaction has failed due to a technical error.
The Account Validation entity has the following fields:
id
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.
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 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
true
(default): activefalse
: inactivenotes
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.
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"}
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.
Handy Tips
name
, email
, contact
, type
and reference_id
.Before you fire the API, ensure you have your API Key id
and Key Secret
readily available. You can
With the following endpoint, you can create a contact.
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
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”
.
Descriptions for the response parameters are present in the
parameters table.Handy Tips
contact_id
, bank_account.name
, bank_account.ifsc
and bank_account.account_number
.Before you fire the API, ensure you have your API Key id
and Key Secret
readily available. You can
With the following endpoint, you can create a fund account of type bank_account
.
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
.
Descriptions for the response parameters are present in the
parameters table.Before you fire the API, ensure you have your API Key id
and Key Secret
readily available. You can
With the following endpoint, you can create a bank account validation transaction.
account_number
mandatory
string
The account from which money should be deducted for the account validation transaction.
fund_account
mandatory
The fund account id you want to validate.
id
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
.
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”
.
Descriptions for the response parameters are present in the
parameters table.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.
Handy Tips
name
, email
, contact
, type
and reference_id
.Before you fire the API, ensure you have your API Key id
and Key Secret
readily available. You can
With the following endpoint, you can create a contact.
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
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”
.
Descriptions for the response parameters are present in the
parameters table.Watch Out!
It is not possible to perform an amount validation for your contact's VPA.
Handy Tips
contact_id
and vpa.address
.Before you fire the API, ensure you have your API Key id
and Key Secret
readily available. You can
With the following endpoint, you can create a fund account of type vpa
.
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
.
Descriptions for the response parameters are present in the
parameters table.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
With the following endpoint, you can create an VPA(UPI) account validation transaction.
account_number
mandatory
string
The account from which money should be deducted for the account validation transaction.
fund_account
mandatory
The fund account id you want to validate.
id
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”
.
Descriptions for the response parameters are present in the
parameters table.Before you fire the API, ensure you have your API Key id
and Key Secret
readily available. You can
With the following endpoint, you can retrieve the details of all account validation transactions you have made.
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
.
from
optional
integer
Timestamp in Unix from when you want to fetch payouts.
to
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
.
Descriptions for the response parameters are present in the
parameters table.Before you fire the API, ensure you have your API Key id
and Key Secret
readily available. You can
With the following endpoint, you can retrieve the details of any particular account validation transaction.
id
mandatory
string
This is the unique identifier linked to the account validation transaction. For example, fav_00000000000001
.
Descriptions for the response parameters are present in the
parameters table.ON THIS PAGE