Create a Customer Identifier With TPV

Create a Customer Identifier using the Razorpay Smart Collect API.

POST /v1/virtual_accounts

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/virtual_accounts \
-H "Content-Type: application/json" \
-d '{
    "receivers": {
        "types": [
            "bank_account"
        ],
        "bank_account":
        {
            "descriptor": "1234567890"
        }

    },
    "allowed_payers": [
      {
        "type": "bank_account",
        "bank_account": {
          "ifsc": "UTIB0000013",
          "account_number": "914010012345679"
        }
      },
      {
        "type": "bank_account",
        "bank_account": {
          "ifsc": "UTIB0000014",
          "account_number": "914010012345680"
        }
      }
    ],
    "description": "Customer Identifier created for Raftar Soft",
    "customer_id": "cust_CaVDm8eDRSXYME",
    "close_by": 1681615838,
    "notes": {
        "project_name": "Banking Software"
    }
}'

Success

{
  "id":"va_DlGmm7jInLudH9",
  "name":"Acme Corp",
  "entity":"virtual_account",
  "status":"active",
  "description":"Customer Identifier created for Raftar Soft",
  "amount_expected":null,
  "notes":{
    "project_name":"Banking Software"
  },
  "amount_paid":0,
  "customer_id":"cust_CaVDm8eDRSXYME",
  "receivers":[
    {
      "id":"ba_DlGmm9mSj8fjRM",
      "entity":"bank_account",
      "ifsc":"RATN0VAAPIS",
      "bank_name": "RBL Bank",
      "name":"Acme Corp",
      "notes":[],
      "account_number":"2223330099089860"
    }
  ],
  "allowed_payers": [
    {
      "type": "bank_account",
      "id":"ba_DlGmm9mSj8fjRM",
      "bank_account": {
        "ifsc": "UTIB0000013",
        "account_number": "914010012345679"
      }
    },
    {
      "type": "bank_account",
      "id":"ba_Cmtnm5tSj6agUW",
      "bank_account": {
        "ifsc": "UTIB0000014",
        "account_number": "914010012345680"
      }
    }
  ],
  "close_by":1681615838,
  "closed_at":null,
  "created_at":1574837626
}

Use this endpoint to create a Customer Identifier. While sharing the details of CIs (created using RBL bank) with the customers, ensure that the fifth character in the IFSC is number 0 and not the letter O. For example, valid IFSC is RATN0VAAPIS and not RATNOVAAPIS.

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/virtual_accounts \
-H "Content-Type: application/json" \
-d '{
    "receivers": {
        "types": [
            "bank_account"
        ],
        "bank_account":
        {
            "descriptor": "1234567890"
        }

    },
    "allowed_payers": [
      {
        "type": "bank_account",
        "bank_account": {
          "ifsc": "UTIB0000013",
          "account_number": "914010012345679"
        }
      },
      {
        "type": "bank_account",
        "bank_account": {
          "ifsc": "UTIB0000014",
          "account_number": "914010012345680"
        }
      }
    ],
    "description": "Customer Identifier created for Raftar Soft",
    "customer_id": "cust_CaVDm8eDRSXYME",
    "close_by": 1681615838,
    "notes": {
        "project_name": "Banking Software"
    }
}'

Success

{
  "id":"va_DlGmm7jInLudH9",
  "name":"Acme Corp",
  "entity":"virtual_account",
  "status":"active",
  "description":"Customer Identifier created for Raftar Soft",
  "amount_expected":null,
  "notes":{
    "project_name":"Banking Software"
  },
  "amount_paid":0,
  "customer_id":"cust_CaVDm8eDRSXYME",
  "receivers":[
    {
      "id":"ba_DlGmm9mSj8fjRM",
      "entity":"bank_account",
      "ifsc":"RATN0VAAPIS",
      "bank_name": "RBL Bank",
      "name":"Acme Corp",
      "notes":[],
      "account_number":"2223330099089860"
    }
  ],
  "allowed_payers": [
    {
      "type": "bank_account",
      "id":"ba_DlGmm9mSj8fjRM",
      "bank_account": {
        "ifsc": "UTIB0000013",
        "account_number": "914010012345679"
      }
    },
    {
      "type": "bank_account",
      "id":"ba_Cmtnm5tSj6agUW",
      "bank_account": {
        "ifsc": "UTIB0000014",
        "account_number": "914010012345680"
      }
    }
  ],
  "close_by":1681615838,
  "closed_at":null,
  "created_at":1574837626
}

Request Parameters

receivers · json object · required

Configuration of desired receivers for the Customer Identifier.

types · array

List of desired receiver types. Possible value is bank_account

bank_account · json object · required

Descriptor details for the Bank Account. This is to be passed only when bank_account is passed as the receiver types.

descriptor · string

A unique, numeric / alphanumeric custom descriptor defined by you for the bank account. The maximum length allowed is 10 digits.

Handy Tips
Please reach out to the support team if you are unable to pass the parameter with bank_account.

allowed_payers · array · required

Details of customer bank accounts which will be allowed to make payments to your Customer Identifier. The parent parameter under which the customer bank account details must be passed as child parameters. You can add account details of 10 allowed payers for a Customer Identifier. For more details, refer to the Third Party Validation section.

type · string · required

The type of account through which the customer will make the payment. Possible value is bank_account.

bank_account · object · required

Indicates the bank account details such as ifsc and account_number.

ifsc · string · required

The IFSC associated with the bank account through which the customer is expected to make the payment.

account_number · string · required

The bank account number through which the customer is expected to make the payment. SBI account numbers can contain zeros preceding actual numbers. You should enter the complete account number, including these zeros, or else the transaction will fail, and the amount will be refunded automatically. For example, if the account number is 00000022234631312, add the complete account number and not just 22234631312.

description · string

A brief description of the Customer Identifier.

customer_id · string

Unique identifier of the customer to whom the Customer Identifier must be tagged. Refer to the Customer API documentation to learn how to create a customer.

notes · json object

Any custom notes you might want to add to the Customer Identifier can be entered here. Refer to the Notes section to learn more.

close_by · integer

UNIX timestamp at which the Customer Identifier is scheduled to be automatically closed. For example, 1681615838. This needs to be passed only if you want the Customer Identifier to be temporary and auto-deleted after a specific usage time.

Response Parameters

id · string

The unique identifier of the Customer Identifier.

name · string

The merchant billing label as it appears on the Dashboard.

entity · string

Indicates the type of entity. Here, it is virtual account.

status · string

Indicates whether the Customer Identifier is in active or closed state.

description · string

A brief description about the Customer Identifier.

amount_expected · integer

The amount expected by the merchant.

amount_paid · integer

The amount paid by the customer into the Customer Identifier.

notes · json object

Any custom notes you might want to add to the Customer Identifier can be entered here. Check the Notes section to know more.

customer_id · string

Unique identifier of the customer the Customer Identifier is linked with. Check the Customer API section to know more.

receivers · json object

Configuration of desired receivers for the Customer Identifier.

id · string

The unique identifier of the Customer Identifier. Sample id for Customer Identifier is ba_Di5gbQsGn0QSz3

entity · string

Name of the entity. Possible value is bank_account.

ifsc · string

The IFSC for the Customer Identifier created. For example, RAZR0000001. This parameter appears in the response only when bank_account is passed as the receiver type.

bank_name · string

The bank associated with the Customer Identifier. For example, RAZR0000001. This parameter appears in the response only when bank_account is passed as the receiver type.

account_number · string

The unique account number provided by the bank. For example, 1112220061746877. This parameter appears in the response only when bank_account is passed as the receiver type.

name · string

The merchant billing label as it appears on the Dashboard. This parameter appears in the response only when bank_account is passed as the receiver type.

notes · json object

Any custom notes you might want to add to the Customer Identifier can be entered here. Check the Notes section to know more. This parameter appears in the response only when bank_account is passed as the receiver type.

allowed_payers · array

Details of customer bank accounts which will be allowed to make payments to your Customer Identifier. The parent parameter under which the customer bank account details must be passed as child parameters. You can add account details of 10 allowed payers for a Customer Identifier. For more details, refer to the Third Party Validation section.

type · string

The type of account through which the customer will make the payment. Possible value is bank_account.

id · string

The unique identifier of the allowed_payers account.

bank_account · object

Indicates the bank account details such as ifsc and account_number.

ifsc · string

The IFSC associated with the bank account through which the customer is expected to make the payment.

account_number · string

The bank account number through which the customer is expected to make the payment.

close_by · integer

UNIX timestamp at which the Customer Identifier is scheduled to be automatically closed. This is returned only if the UNIX timestamp was specified during the Customer Identifier creation. There is no expiry time for a Customer Identifier unless specified during creation.

closed_at · integer

UNIX timestamp at which the Customer Identifier is automatically closed.

created_at · integer

UNIX timestamp at which the Customer Identifier was created.

Errors

The API `<key/secret> ` provided is invalid.

Code: 4xx

• Occurs when there is a mismatch between the API credentials passed in the API call and the API credentials generated on the Dashboard.
• customer_id is not correct.

Solution:

• Make sure that the API keys are active and entered correctly. Also, make sure there are no whitespaces before or after the API keys.
• Make sure that the customer_id and the API keys used belong to the same account and same mode, whether test or live respectively.

The `field name` is required

Code: 400

Occurs when a mandatory field is empty.

Solution: Make sure that all the mandatory fields are filled.

The id provided does not exist

Code: 400

Occurs when the customer_id passed is wrong or does not belong to the identifier associated to the API keys used.

Solution: Make sure that the customer_id and the API keys used belong to the same identifier and same mode, whether test or live respectively.

only 10 allowed payers can be added

Code: 400

Occurs when more than 10 allowed payers are added in the Dashboard.

Solution: When creating the Customer Identifier, allowed payers cannot be more than 10.

Account validation is only applicable on bank account as receiver type.

Code: 400

This error occurs when you try to add an allowed payer account on a Customer Identifier with VPA added as a receiver (with or without a Bank account).

Solution: Allowed payers must have bank account details and not VPA.

The bank account IFSC field is required when the bank is present ( in allowed payers)

Code: 400

This error occurs when you do not pass the IFSC code in the request.

Solution: Provide IFSC code for the allowed payers bank account.

Invalid IFSC OR IFSC must be 11 Characters

Code: 400

This error occurs when you pass an incorrect IFSC code in the request. An IFSC must be 11 characters.

Solution: Pass the correct IFSC code of the allowed payers bank account.