Smart Collect

Create and manage virtual accounts. Fetch payment details using Razorpay Smart Collect APIs.


You can create

to accept large payments from your customers in the form of bank transfers via NEFT, RTGS and IMPS.

Changelog

We have deprecated the qr receiver type from our APIs. vpa and bank_account are the only supported receiver types. (Jun 2022).

  • Virtual accounts are similar to bank accounts wherein customers can transfer payments.
  • Create, retrieve and close virtual accounts using the Smart Collect APIs.
  • The virtual account response is an array that defines what receivers are available for the virtual account. It contains:
    • attributes such as id and customer_id
    • and a field, receivers

Know more about

.

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

The Smart Collect entity has the following fields:

id

string The unique identifier of the virtual account.

name

string The merchant billing label as it appears on the Razorpay Dashboard.

entity

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

status

string Indicates whether the virtual account is in active or closed state.

description

string A brief description about the virtual account.

amount_paid

integer The amount paid by the customer into the virtual account.

notes

json object Any custom notes you might want to add to the virtual account can be entered here. Know more about

.

customer_id

string Unique identifier of the customer the virtual account is linked with. Know more about

.

receivers

json object Configuration of desired receivers for the virtual account.

id

string The unique identifier of the virtual bank account or virtual UPI ID. Sample IDs for:

  • virtual bank account: ba_Di5gbQsGn0QSz3
  • virtual UPI ID: vpa_CkTmLXqVYPkbxx

entity

string Name of the entity. Possible values are:

  • bank_account
  • vpa

ifsc

string The IFSC for the virtual bank account 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 virtual bank account. 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 Razorpay 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 virtual bank account or virtual UPI ID can be entered here. Know more about

. This parameter appears in the response only when bank_account is passed as the receiver type.

username

string The UPI ID consists of the username and the bank handle. The username consists of the namespace (assigned by the bank to Razorpay), the merchant prefix (which can be customized by you) and the descriptor (which you provide to identify the customer). The unique identifier which forms the first half of the virtual UPI ID. For example, rpy.payto00000gaurikumar. This parameter appears in the response only when vpa is passed as the receiver type. The descriptor can be 10 characters only.

handle

string The bank name that forms the second half of the virtual UPI ID. For example, icici. This parameter appears in the response only when vpa is passed as the receiver type.

address

string The UPI ID that combines the username and the handle with the @ symbol. For example, rpy.payto00000gaurikumar@icici. This parameter appears in the response only when vpa is passed as the receiver type.

close_by

integer UNIX timestamp at which the virtual account is scheduled to be automatically closed. The time must be at least 15 minutes after current time. The date range can be set till 2147483647 in UNIX timestamp format (equivalent to Tuesday, January 19, 2038 8:44:07 AM GMT+05:30).

Handy Tips
Any request beyond 2147483647 UNIX timestamp will fail.

closed_at

integer UNIX timestamp at which the virtual account is automatically closed.

created_at

integer UNIX timestamp at which the virtual account was created.

You can create and manage virtual accounts using APIs or from the

.

The following entity creates a Smart Collect account to accept large payments from your customers in the form of bank transfers via NEFT, RTGS and IMPS.

POST
/virtual_accounts

Handy Tips

You can customise the merchant prefix of the vpa (payto00000) as per your business requirements. This is an on-demand feature and is not available by default. To enable creation of custom merchant prefix, raise a request on our

.

receivers

mandatory

json object Configuration of desired receivers for the virtual account.

types

array List of desired receiver types. Possible values:

  • bank_account
  • vpa

vpa

optional

json object Descriptor details for the virtual UPI ID. This is to be passed only when vpa is passed as the receiver types.

descriptor

string You can provide a custom descriptor for the UPI ID. This is a unique identifier provided by you to identify the customer. For example, gaurikumar and akashkumar are the descriptors in the usernames rpy.payto00000gaurikumar and rpy.payto00000akashkumar respectively. The combination of merchant prefix and descriptor must be 20 characters. The length of the merchant prefix can vary between 4-10 characters, and the length of descriptor from 10-16 characters.

bank_account

optional

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

descriptor

string You can provide a custom descriptor for the bank account. This allows generation of bank account numbers in a sequence defined by you. The maximum length allowed is 10 digits.

Handy Tips
The descriptor parameter can be passed for both bank_account and vpa receiver types. Please reach out to the support team if you are unable to pass the parameter with bank_account.

description

optional

string A brief description of the virtual account.

customer_id

optional

string Unique identifier of the customer to whom the virtual account must be tagged. Create a customer using the

.

notes

optional

json object Any custom notes you might want to add to the virtual account can be entered here. Know more about

.

close_by

optional

integer UNIX timestamp at which the virtual account is scheduled to be automatically closed. The time must be at least 15 minutes after current time. The date range can be set till 2147483647 in UNIX timestamp format (equivalent to Tuesday, January 19, 2038 8:44:07 AM GMT+05:30).


Handy Tips

Any request beyond 2147483647 UNIX timestamp will fail.

Handy Tips

While sharing the details of VAs (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.

Use the sample codes to create a virtual account with vpa as the receiver type.

Use the sample code to create a virtual account with both bank_account and vpa receiver types.

Descriptions for the response parameters are present in the

.

The following endpoint retrieves details for a single virtual account by ID.

GET
/virtual_accounts/:id

id

mandatory

string The unique identifier of the virtual account whose details are to be fetched.

Descriptions for the response parameters are present in the

.

The following endpoint retrieves details for all virtual accounts.

GET
/virtual_accounts

from

optional

integer Timestamp, in seconds, from when virtual accounts are to be fetched.

to

optional

integer Timestamp, in seconds, till when virtual accounts are to be fetched.

count

optional

integer Number of virtual accounts to be fetched. The default value is 10 and the maximum value is 100. This can be used for pagination, in combination with skip.

skip

optional

integer Number of records to be skipped while fetching the virtual accounts. This can be used for pagination, in combination with count.

Descriptions for the response parameters are present in the

.

The following endpoint retrieve payment details for a single virtual account by id.

GET
/virtual_accounts/:id/payments

id

mandatory

string The unique identifier of the virtual account for which the payment details are to be fetched.

from

optional

integer Timestamp, in seconds, from when payments are to be fetched.

to

optional

integer Timestamp, in seconds, till when payments are to be fetched.

count

optional

integer Number of payments to be fetched. The default value is 10 and the maximum value is 100. This can be used for pagination, in combination with skip.

skip

optional

integer Number of records to be skipped while fetching the payments. This can be used for pagination, in combination with count.

Descriptions for the response parameters are present in the

.

You can retrieve details of a payment using the Payment ID and transfer method API.

The following endpoint retrieve payment details using transfer method API.

GET
/payments/:id/bank_transfer

Handy Tips

If Razorpay does not receive the bank account information of the customer from the remitting bank, the payer_bank_account key will be set to null.

id

mandatory

string The unique identifier of the payment made to the virtual account.

id

string The unique identifier of the bank transfer.

entity

string The name of the entity. Here, it is bank_transfer.

payment_id

string The unique identifier of the payment.

mode

string The mode of bank transfer used. Possible values are:

  • 'NEFT'
  • RTGS
  • IMPS
  • UPI

bank_reference

string Unique reference number provided by the bank for the transaction.

payer_bank_account

object The payer bank account details from which payment is received.

id

string The unique identifier of the customer's bank account.

entity

string The name of the entity. Here, it is bank_account.

ifsc

string The IFSC associated with the bank account.

bank_name

string The name of the bank in which the customer has an account.

notes

object Any custom notes added to the virtual bank account.

account_number

string The unique account number of the customer.

virtual_account_id

string The unique identifier of the virtual account.

virtual_account

object Details of the virtual account.

id

string The unique identifier of the virtual account.

name

string The merchant billing label as it appears on Razorpay Dashboard.

entity

string The name of the entity. Here, it is virtual account.

status

string Indicates the status of the virtual account. Possible values are:

  • active
  • closed

description

string A brief description about the virtual account.

amount_paid

integer The amount paid by the customer to the virtual account.

notes

object Any custom notes added during the creation of the virtual account.

customer_id

string The unique identifier of the customer the virtual account is linked with. Know more about

.

receivers

object Configuration of desired receivers for the virtual account.

id

string The unique identifier of the virtual bank account. For example, ba_Di5gbQsGn0QSz3.

entity

string The name of the entity. Here, it is bank_account.

ifsc

string The IFSC for the virtual bank account created. For example, RATN0VAAPIS.

bank_name

string The bank associated with the virtual bank account. For example, RBL.

account_number

string The unique account number provided by the bank. For example, 1112220061746877.

name

string The merchant billing label as it appears on Razorpay Dashboard.

notes

object Any custom notes added during the creation of the virtual account.

close_by

integer UNIX timestamp at which the virtual account is scheduled to be automatically closed. The time must be at least 15 minutes after current time. The date range can be set till 2147483647 in UNIX timestamp format (equivalent to Tuesday, January 19, 2038 8:44:07 AM GMT+05:30).

Handy Tips
Any request beyond 2147483647 UNIX timestamp will fail.

closed_at

integer UNIX timestamp at which the virtual account is automatically closed.

created_at

integer UNIX timestamp at which the virtual account was created.

The following endpoint retrieve payment details using transfer method API.

GET
/payments

count

optional

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

skip

optional

integer Number of records to be skipped while fetching the payments.

va_transaction_id

optional

integer The unique id of the transaction done via a Virtual Account.

virtual_account

optional

boolean The product used to fetch is Virtual Accounts.
Possible values: 1

Descriptions for the response parameters are present in the

.

The following endpoint retrieve payment details using Payment ID API.

GET
/payments/:id/upi_transfer

id

mandatory

string The unique identifier of the payment made to the virtual account.

id

string The unique identifier of the UPI transfer.

entity

string The name of the entity. Here, it is upi_transfer.

amount

integer The amount paid by the customer.

payer_vpa

string The UPI ID of the customer that is used to make the payment.

payer_bank

string The name of the customer's bank.

payer_account

string The bank account number of the customer that is linked to the UPI ID.

payer_ifsc

string The IFSC associated with the bank account.

payment_id

string The unique identifier of the payment made by the customer.

npci_reference_id

string The unique reference number provided by NPCI for the payment.

virtual_account_id

string The unique identifier of the virtual account.

virtual_account

object Details of the virtual account.

id

string The unique identifier of the virtual account.

name

string The merchant billing label as it appears on Razorpay Dashboard.

entity

string The name of the entity. Here, it is virtual account.

status

string Indicates the status of the virtual account. Possible values are:

  • active
  • closed

description

string A brief description about the virtual account.

amount_paid

integer The amount paid by the customer into the virtual account.

notes

object Any custom notes added during the creation of the virtual account.

customer_id

string The unique identifier of the customer the virtual account is linked with. For more details, refer to the

.

receivers

object Configuration of desired receivers for the virtual account.

id

string The unique identifier of the virtual UPI ID. For example, vpa_CkTmLXqVYPkbxx.

entity

string The name of the entity. Here, it is vpa.

username

string The unique identifier which forms the first half of the virtual UPI ID. For example, rpy.payto00000gaurikumar.

handle

string The bank name that forms the second half of the virtual UPI ID. For example, icici.

address

string The UPI ID that combines the username and the handle with the @ symbol. For example, rpy.payto00000gaurikumar@icici. This parameter appears in the response only when vpa is passed as the receiver type.

close_by

integer UNIX timestamp at which the virtual account is scheduled to be automatically closed. The time must be at least 15 minutes after current time. The date range can be set till 2147483647 in UNIX timestamp format (equivalent to Tuesday, January 19, 2038 8:44:07 AM GMT+05:30).

Handy Tips
Any request beyond 2147483647 UNIX timestamp will fail.

closed_at

integer UNIX timestamp at which the virtual account is automatically closed.

created_at

integer UNIX timestamp at which the virtual account was created.

The following endpoint processes refunds for a payment made towards a virtual account.

POST
/payments/:id/refund

id

mandatory

string The unique identifier of the payment to be refunded.

amount

optional

integer The amount to be refunded. Amount should be in the smallest unit of the currency in which the payment was made.

  • For a partial refund, enter a value lesser than the payment amount. For example, if the payment amount is ₹1500 and you want to refund only ₹500, you must pass 50000.
  • For full refund, enter the entire payment amount. If amount parameter is not passed, the entire payment amount will be refunded.

speed

optional

string The speed at which the refund is to be processed. The default value is normal. Refund will be processed via the normal speed and the customer will receive the refund within 5-7 working days.

notes

optional

json object Key-value pairs used to store additional information. A maximum of 15 key-value pairs can be included.

receipt

optional

string A unique identifier provided by you for your internal reference.

Descriptions for the response parameters are present in the

.

Know more about

to perform other refund-related operations:

  • Fetch a particular refund or a list of refunds for a payment id.
  • Update a refund to modify the Notes field.

Watch Out!

If you had created a virtual account with a receiver, for example, bank account, you cannot add another bank account receiver or replace it. Similarly, if you had created a virtual account with only a VPA receiver, you cannot replace or update it.

The following endpoint adds a receiver to an existing virtual account.

POST
/virtual_accounts/:id/receivers

id

mandatory

string The unique identifier of the virtual account to which another receiver type is to be added.

types

mandatory

array The receiver type to be added to the virtual account. Possible values are:

  • bank_account
  • vpa

vpa

optional

json object Descriptor details for the virtual UPI ID. This is to be passed only when vpa is passed as the receiver types.

descriptor

string You can provide a custom descriptor for the UPI ID. This is a unique identifier provided by you to identify the customer. For example, gaurikumar and akashkumar are the descriptors in the usernames rpy.payto00000gaurikumar and rpy.payto00000akashkumar respectively. The combination of merchant prefix and descriptor must be 20 characters. If you go ahead with the default merchant prefix, you will get 10 characters. Hence the descriptor should be 10 characters only.

Handy Tips
If a user tries to input 11 or more characters in a descriptor, our API will throw an error for invalid character length.

The following endpoint lets you update your virtual account.

POST
/virtual_accounts/:id

id

mandatory

string The unique identifier of the virtual account to which another receiver type is to be added.

Handy Tips

You cannot update the expiry date of a virtual account that has been closed.

id

mandatory

string The unique identifier of the virtual account which you want to update.

descriptor

string You can provide a custom descriptor for the UPI ID. This is a unique identifier provided by you to identify the customer. For example, gaurikumar and akashkumar are the descriptors in the usernames rpy.payto00000gaurikumar and rpy.payto00000akashkumar respectively. The descriptor length should be 10 characters only.

Descriptions for the response parameters are present in the

.

close_by

optional

integer UNIX timestamp at which the virtual account is scheduled to be automatically closed. The time must be at least 15 minutes after current time. The date range can be set till 2147483647 in UNIX timestamp format (equivalent to Tuesday, January 19, 2038 8:44:07 AM GMT+05:30).

Watch Out!
Any request beyond 2147483647 UNIX timestamp will fail.

description

optional

string A brief description of the virtual account.

notes

optional

json object Any custom notes you might want to add to the virtual account can be entered here. Refer to the

to learn more.

The following endpoint closes a virtual account.

POST
/virtual_accounts/:id/close

id

mandatory

string The unique identifier of the virtual account that is to be closed.

Descriptions for the response parameters are present in the

.