Fund/Bank Account Validation Composite

Coming Soon!

This API allows you to create contact, it's fund account and validate the bank account (using penny-drop/penniless) and VPA IDs of your customers, in a single API call.

Watch Out!

Fund Account Validation is possible only for RazorpayX Lite.
This feature is not available in test mode.
It is mandatory to
allowlist IPs
that you use while making payouts via APIs or the request will fail.

Account Validation States

After you validate a Fund Account, it moves to the following statuses in its life cycle.

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

List of Endpoints

Before you fire APIs, keep your Key id and Key Secret available. You can

generate API keys

in Live Mode on the

RazorpayX Dashboard

API Endpoint	Description
Validate a Bank Account	Create Contact, Fund Account with bank details and Validate the Contact's bank account information in a single API call.
Validate a VPA	Create Contact, Fund Account with VPA and Validate the Contact's bank account information in a single API call.
Fetch all Account Validation Transactions	Retrieves all account validation transactions.
Fetch an Account Validation Transaction with ID	Retrieves a single account validation transaction with ID.

Composite Account Validation Entity

The Account Validation entity has the following fields:

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

entity

string Here it will be fund_account.validation.

status

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

created
completed
failed

validation_results

object Result of the validation.

account_status

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

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

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.

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.

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

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.

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

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.

{
  "id": "fav_00000000000001",
  "entity": "fund_account.validation",
  "status": "completed",
  "validation_results": {
      "account_status": "valid",
      "registered_name": "Gaurav Kumar",
      "details": "The beneficiary account is valid." ,
      "name_match_score": 100
   },
  "status_details": {
    "description": "Validation request is completed",
    "source": "beneficiary_bank",
    "reason": "validation_completed"
    },
  "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":"gaurav.kumar@example.com",
          "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."
          }
      }
  }
}