API ReferenceIntegrationsKnowledge Base

Route

You can onboard a vendor and manage his linked account using the Account Management APIs. This can also be achieved on your Razorpay Dashboard, by clicking Route on the left sidebar menu.

The following details are required in order to create a linked account:

  1. Primary details - Linked account name, contact number.
  2. Bank details - Account number, account type, IFSC, beneficiary name.

Once an linked account is created, it will be assigned an account_id which can be used in the APIs explained below.

Transfer Entity#

The attributes of the transfer entity are listed below:

id string
Transfer ID
source string
Entity ID of the transfer source
receipt string
Entity ID of the transfer destination.
amount integer
Transfer amount.
currency string
3 character ISO currency code.
amount_reversed integer
Amount reversed from this transfer for refunds.
on_hold boolean
Boolean representing whether the account settlement for transfer is on hold.
on_hold_until integer
Timestamp. Until when should the settlement of the transfer be put on hold.
created_at timestamp
UNIX timestamp of record creation.

In the sample request given, transfers to multiple linked accounts are specified, each with a different amount. The payment transferred to these accounts will be settled to their bank accounts as per the settlement_period defined by you for each linked account.

Create Payments#

You can create and capture payments in the regular payments flow, using Razorpay Checkout and Payment APIs.

For disbursing payments on Razorpay Route, there is an additional step in the payment flow called transfers which is described below:

  1. Customer pays the amount to your account using normal payment flow.
  2. Once the payment is successful and marked as captured, you can now initiate a payment transfer to linked accounts with a transfer API call. You have to specify the details of the account_id and amount.

Transfer Payments#

Once the payment is successful and marked as captured, you can now initiate a payment transfer to linked accounts with a transfer API call. You have to specify the details of the account_id and amount.

/payments/:id/transfers

This API transfers a captured payment to one or more linked accounts using account_id. On successful transfer, the API will respond with a collection of transfer entities created for the payment.

Transfer Requirements:

  • The transfer method requires your account to have sufficient funds to process the transfer to linked account, and will fail incase of insufficient funds.
  • Only those payments that are in captured state are transferred.
  • Payment transfer can be requested multiple times, but only one transfer can be made to a linked account per payment_id. This holds good as long as the total transfer amount requested does not exceed the captured payment amount.
  • Payments cannot be transferred after a refund is initiated on the payment_id.

Note:
All our APIs take amount in Paisa, and not Rupees.

Fetch Transfers#

This API retrieves the collection of all transfers created on the payment_id.

/payments/:id/transfers

Once the settlement against the transfer is processed a webhook settlement.processed is sent which contains a recipient_settlement_id.

The details of the settlement can be obtained by appending
?expand[]=recipient_settlement as query parameter to the fetch transfer request which would return a settlement entity along with the transfer entity.

Refund Payments#

A payment can be refunded to a customer using Refunds API.

When refunding a payment that has transfers, the amount for the refund is deducted from your main account balance. In order to recover the amount from linked accounts, the reverse_all parameter can be set to 1 in the refund POST request. This will recover the amount from linked accounts for every transfer made on the payment, before processing the refund to the customer.

Note:
The reverse_all attribute is optional. You may also choose to manually reverse transfers created on a payment by using the /transfers/:id/reversals which is described later on this page.

Automated Reversals:
Reversals can be automated with the reverse_all attribute in the following refund scenarios:

  • Full refund
  • Partial refund for a payment transferred to a single account.
    For partial refunds on a payment transferred to multiple accounts - the reverse_all parameter cannot be applied, since Razorpay cannot determine which transfer to partially reverse. You will have to use the transfer reversal API to achieve reversals on this payment.

In the example given on the side, the amount specified in the amount parameter (i.e., 15000) is the amount that will be refunded to the customer. The amount that will be recovered from the linked accounts is the sum of all transfers made to each of those accounts, for the payment_id.

A new reversal entity is created internally and linked for every reversals defined by the transfer_id.

The attributes of the reversal entity are defined below:

id string
Reversal ID
transfer_id string
Transfer ID that was reversed.
amount integer
Amount reversed
currency string
3 character ISO currency code.
created_at timestamp
Timestamp when the reversal was created.

Direct Transfers#

You can transfer funds to your linked accounts directly without linking any payments to it. With direct transfer, you can transfer an amount from your balance to the linked accounts' balance.

/transfers

This API creates a direct transfer of funds from your account to linked account. On successful creation, the API responds with the created transfer entity.

Transfer Reversals#

While a transfer moves funds from your account to linked accounts, a reversal can move funds back into your account.

Reversal can be created on any transfer_id.

Retrieve Transfer Entity#

/transfers/:id

This API retrieves a transfer entity by its transfer_id, as shown on the right.

Create Settlements#

Transfers are settled to linked accounts as per the settlement_period defined for the account. You can also choose to hold account settlements per transfer or per linked account.

Hold Settlements For Transfers#

When transferring a payment to an account, you can choose to put the transfer on hold indefinitely or until a defined time. These settings can be toggled or modified anytime via the API provided, until the settlement is made. When a transfer is put on hold, the settlement for the linked account is deferred until the hold is released.

The following parameters can be sent for each transfer in the payment transfer API defined above:

on_hold boolean (0 / 1)
If set to 1, the transfer is put on hold and settlement to the linked account is deferred until the hold is removed. (Default: 0).

For example: Suppose the settlement scheduled for a linked account - acc_a1b2c3d4e5f6g7 was defined as T+10 days, the transfer created with the request defined below will not be settled after 10 days - as long as the hold is maintained. If the hold is disabled on T+15, the amount will be settled to the linked account by the next working day.
on_hold_until integer
Epoch timestamp. If set, Razorpay will hold the settlement of the transfer to the linked account until the timestamp provided elapses.

For example: If a transfer is created with on_hold_until timestamp defined, we will hold the settlement of this transfer to the linked account until the timestamp defined has elapsed. Once elapsed, the transfer amount will be settled to the linked account by the next working day.

When using this parameter, on_hold must be sent and set to 1. Additionally, the timestamp value provided must be greater than the current timestamp.

Settlement Schedule Override:
The settlement schedule defined for the linked account takes higher preference over the on_hold and on_hold_until functionality. This simply means that defined settlement schedule is the the minimum time required for the transfer to be settled.

Examples:
For a T+10 settlement schedule -

  • If a transfer was created with on_hold=1 and then released on day T+7, the settlement will only go out on day T+10.
  • If a transfer was created with on_hold=1 and on_hold_until=1491567400 (assume the timestamp 1491567400 corresponds to 7 days after transfer) - then transfer's on_hold will change to false on day T+7, but the settlement will only go out on day T+10.

In the example request given on the side, a transfer of INR 10000 to account_id acc_a1b2c3d4e5f6g7 is created and put on hold.

Modify Transfer Hold#

/transfers/:id

The transfer hold settings can be modified anytime by sending a PATCH request on the transfer_id. On successful request, the API responds with the modified transfer entity.

Note:
You cannot change this setting after the transfer has been settled to the linked account.

Curl
‹›