You can transfer funds to your Linked Accounts using Razorpay Route Transfer APIs. Know more about

transfers

and the

related fees

Transfer Requirements

Below are the requirements to initiate a transfer:

Your account must have sufficient funds to process the transfer to the Linked Account. The transfer will fail in case of insufficient funds.
You can only transfer the captured payments.
You can create more than one transfer on a payment_id. However, the total transfer amount (payment amount + fee) should not exceed the captured payment amount.
You cannot request a transfer on payment once a refund has been initiated.

Types of Transfers

You can transfer funds to Linked Accounts using one of the following methods:

Transfer via Orders

You can set up a transfer at the time of order creation.

Watch Out!
If a Transfer via Order initiated by you fails, we will retry this transfer starting from the next day on consecutive days. There will be a maximum of 3 retries.
Transfer via Payments

You can initiate a transfer after you receive and capture the payment from the customer.
Direct Transfer

You can initiate a transfer using the existing funds directly from your Razorpay account.

Feature Request

This is an on-demand feature. Please raise a request with our
Support team
to get this feature activated on your Razorpay account.
Watch this video to know how to raise a feature enablement request on the Razorpay Dashboard.

Transfer Entity

Route transfers can be performed only on captured payments. You can capture payments from the

Razorpay Dashboard

or using the

Payment Capture API

The transfer entity has the following attributes:

string Unique identifier of the transfer.

entity

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

transfer_status

string The status of the transfer. Possible values are:

created
pending
processed
failed
reversed
partially_reversed

settlement_status

string The status of the settlement. Possible values are:

pending
on_hold
settled

source

string Unique identifier of the transfer source. The source can be a payment or an order.

recipient

string Unique identifier of the transfer destination, that is, the linked account.

amount

integer The amount to be transferred to the linked account, in paise. For example, for an amount of ₹200.35, the value of this field should be 20035.

currency

string ISO currency code. We support route transfers only in INR.

amount_reversed

integer Amount reversed from this transfer for refunds.

notes

json object Set of key-value pairs that can be associated with an entity. These pairs can be useful for storing additional information about the entity. A maximum of 15 key-value pairs, each of 256 characters (maximum), are supported. For example, "region": "south", "city": "Bangalore".

error

Provides error details that may occur during transfers.

code

string Type of the error.

description

string Error description.

field

string Name of the parameter in the API request that caused the error.

source

string The point of failure in the specific operation. For example, customer, business and so on.

step

string The stage where the transaction failure occurred. Stages can be different depending on the payment method used to make the transaction.

reason

string The exact error reason. It can be handled programmatically.

linked_account_notes

array List of keys from the notes object which needs to be shown to linked accounts on their Dashboard. For example, "region", "city". Only the keys will be shown, not values.

on_hold

boolean Indicates whether the account settlement for transfer is on hold. Possible values:

1 - Puts the settlement on hold.
0 - Releases the settlement.

on_hold_until

integer Timestamp, in Unix format, indicates until when the settlement of the transfer must be put on hold. If no value is passed, the settlement is put on hold indefinitely.

recipient_settlement_id

string Unique identifier of the settlement.

created_at

integer Timestamp, in Unix, at which the record was created.

{
   "entity":"collection",
   "count":2,
   "items":[
      {
         "id":"trf_ECB6hP5cyN30pU",
         "entity":"transfer",
         "transfer_status":"failed",
         "settlement_status":null,
         "source":"pay_EB1R2s8D4vOAKG",
         "recipient":"acc_CNo3jSI8OkFJJJ",
         "amount":100,
         "currency":"INR",
         "amount_reversed":0,
         "notes":{
            "name":"Saurav Kumar",
            "roll_no":"IEC2011026"
         },
         "error":{
            "code":"BAD_REQUEST_TRANSFER_INSUFFICIENT_BALANCE",
            "description":"Transfer failed due to insufficient balance",
            "field":null,
            "source":"transfer",
            "step":"balance_check",
            "reason":"insufficient_balance"
         },
         "fees":1,
         "tax":0,
         "on_hold":false,
         "on_hold_until":null,
         "recipient_settlement_id":null,
         "created_at":1580712811,
         "linked_account_notes":[
            "roll_no"
         ],
         "processed_at":1580712811
      },
      {
         "id":"trf_ECB6hP5cyN30pU",
         "entity":"transfer",
         "transfer_status":"failed",
         "settlement_status":null,
         "source":"pay_EB1R2s8D4vOAKG",
         "recipient":"acc_CNo3jSI8OkFJJJ",
         "amount":100,
         "currency":"INR",
         "amount_reversed":0,
         "notes":{
            "name":"Saurav Kumar",
            "roll_no":"IEC2011026"
         },
         "error":{
            "code":"BAD_REQUEST_PAYMENT_FEES_GREATER_THAN_AMOUNT",
            "description":"Transfer amount was greater than amount available for transfer",
            "field":null,
            "source":"transfer",
            "step":"amount_validation",
            "reason":"transfer_amount_higher_than_balance"
         },
         "fees":1,
         "tax":0,
         "on_hold":false,
         "on_hold_until":null,
         "recipient_settlement_id":null,
         "created_at":1580712811,
         "linked_account_notes":[
            "roll_no"
         ],
         "processed_at":1580712811
      }
   ]
}

Transfer Status

The following table lists transfer statuses and their description:

Status	Description
`created`	As soon as the transfer is initiated, it moves to the `created` state. Transfers via payments and direct transfers will immediately move to the `pending` state from the `created` state. However, the transfer will stay in the `created` state for transfers via orders until the order is paid.
`pending`	The transfer will be in the `pending` state till the transfer is waiting to be processed.
`processed`	Once the transfer is processed, the status will change from `pending` to `processed` . You can initiate the reversal if required.
`failed`	If the transfer processing fails because of errors like insufficient balance, the transfer status will change to the `failed` state. You can proceed to create a new transfer request.
`reversed`	If the complete reversal is done for the transfer, then it will be marked as `reversed` .
`partially_reversed`	If the partial reversal is done on transfer, it will be marked as `partially_reversed` .

Settlement Status

The following table lists settlement statuses and their description:

Status	Description
`pending`	This status indicates that the transfer is processed and the settlement is pending. You can create the reversal if required.
`on_hold`	If you have used the `on_hold` parameter to hold settlements for the transfer and don’t pass the `on_hold_until` parameter to define till when it should be `on_hold` , the transfer will be on hold indefinitely. We will mark such transfers as `on_hold.`
`settled`	When the transfer is settled to the Linked Account.

Create Transfers from Orders

You can set up a transfer of funds when creating an order using the Orders API. This can be done by passing the transfers parameters as part of the Order API request body.

The following endpoint lets you transfer the funds while creating an order.

POST

/orders

{
  "id": "order_JJCYnu3hipocHz",
  "entity": "order",
  "amount": 2000,
  "amount_paid": 0,
  "amount_due": 2000,
  "currency": "INR",
  "receipt": null,
  "offer_id": null,
  "offers": {
    "entity": "collection",
    "count": 0,
    "items": []
  },
  "status": "created",
  "attempts": 0,
  "notes": [],
  "created_at": 1649931742,
  "transfers": [
    {
      "id": "trf_JJCYnw77tqUT9r",
      "entity": "transfer",
      "status": "created",
      "source": "order_JJCYnu3hipocHz",
      "recipient": "acc_IRQWUleX4BqvYn",
      "amount": 1000,
      "currency": "INR",
      "amount_reversed": 0,
      "notes": {
        "branch": "Acme Corp Bangalore North",
        "name": "Gaurav Kumar"
      },
      "linked_account_notes": [
        "branch"
      ],
      "on_hold": true,
      "on_hold_until": 1671222870,
      "recipient_settlement_id": null,
      "created_at": 1649931742,
      "processed_at": null,
      "error": {
        "code": null,
        "description": null,
        "reason": null,
        "field": null,
        "step": null,
        "id": "trf_JJCYnw77tqUT9r",
        "source": null,
        "metadata": null
      }
    },
    {
      "id": "trf_JJCYnxe5GV19Kk",
      "entity": "transfer",
      "status": "created",
      "source": "order_JJCYnu3hipocHz",
      "recipient": "acc_IROu8Nod6PXPtZ",
      "amount": 1000,
      "currency": "INR",
      "amount_reversed": 0,
      "notes": {
        "branch": "Acme Corp Bangalore South",
        "name": "Saurav Kumar"
      },
      "linked_account_notes": [
        "branch"
      ],
      "on_hold": false,
      "on_hold_until": null,
      "recipient_settlement_id": null,
      "created_at": 1649931742,
      "processed_at": null,
      "error": {
        "code": null,
        "description": null,
        "reason": null,
        "field": null,
        "step": null,
        "id": "trf_JJCYnxe5GV19Kk",
        "source": null,
        "metadata": null
      }
    }
  ]
}

Request Parameters

amount

mandatory

integer The transaction amount, in paise. For example, for an amount of ₹299.35, the value of this field should be 29935.

currency

mandatory

string The currency in which the transaction should be made. We support only INR for Route transactions.

receipt

optional

string Unique identifier that you can use for internal reference.

transfers

Details regarding the transfer.

account

mandatory

string Unique identifier of the linked account to which the transfer is to be made.

amount

mandatory

integer The amount to be transferred to the linked account. For example, for an amount of ₹200.35, the value of this field should be 20035. This amount cannot exceed the order amount.

currency

mandatory

string The currency in which the transfer should be made. We support only INR for Route transactions.

notes

linked_account_notes

array List of keys from the notes object which needs to be shown to linked accounts on their Dashboard. For example, "region", "city". Only the keys will be shown, not values.

on_hold

mandatory

boolean Indicates whether the account settlement for transfer is on hold. Possible values:

1 - Puts the settlement on hold.
0 - Releases the settlement.

on_hold_until

optional

integer Timestamp, in Unix format, that indicates until when the settlement of the transfer must be put on hold. If no value is passed, the settlement is put on hold indefinitely.

Response Parameters

string Unique identifier of the Order created.

entity

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

amount

integer The Order amount, in paise. For example, for an amount of ₹299.35, the value of this field should be 29935.

amount_paid

integer The amount paid against the Order.

amount_due

integer The amount pending against the Order.

currency

string The currency in which the order should be created. We support only INR for Route transactions.

receipt

string Unique identifier that you can use for internal reference.

status

string The status of the Order. Below are the possible values:

created
attempted
paid

notes

created_at

integer Timestamp in Unix. This indicates the time of the order created.

transfers

Details regarding the transfer.

string Unique identifier of the transfer.

recipient

string Unique identifier of the linked account to which the transfer is to be made.

transfer_status

string The status of the transfer. Possible values are:

created
pending
processed
failed
reversed
partially_reversed

settlement_status

string The status of the settlement. Possible values are:

pending
on_hold
settled

amount

integer The amount to be transferred to the linked account, in paise. For example, for an amount of ₹200.35, the value of this field should be 20035.This amount cannot exceed the order amount.

currency

string The currency in which the transfer should be made. We support only INR for Route transactions.

notes

linked_account_notes

array List of keys from the notes object which needs to be shown to linked accounts on their Dashboard. For example, "region", "city". Only the keys will be shown, not values.

on_hold

boolean Indicates whether the account settlement for transfer is on hold. Possible values:

1 - Puts the settlement on hold.
0 - Releases the settlement.

on_hold_until

integer Timestamp, in Unix, that indicates until when the settlement of the transfer must be put on hold. If no value is passed, the settlement is put on hold indefinitely.

error

Provides error details that may occur during transfers.

code

string Type of the error.

description

string Error description.

field

string Name of the parameter in the API request that caused the error.

source

string The point of failure in the specific operation. For example, customer, business and so on.

step

string The stage where the transaction failure occurred. Stages can be different depending on the payment method used to make the transaction.

reason

string The exact error reason. It can be handled programmatically.

Error Response Parameters

Given below is a list of possible errors you may face while creating transfers via orders.

Error	Cause	Solution
The api key/secret provided is invalid	This error occurs when there is a mismatch between the API credentials passed in the API call and the API credentials generated on the dashboard.	Make sure the API Keys are active and entered correctly. Also, there should not be any whitespaces before or after the keys.
The amount must be atleast INR 1.00	This error occurs when the amount is less than the minimum amount. The transaction amount expressed in the currency subunit, such as paise (in INR) should always be greater than or equal to 100.	Make sure the amount is equal to or greater than the minimum amount of ₹100.
The input field is required	This error occurs when a mandatory field is empty.	Make sure to fill in all the mandatory fields.
The currency should be INR for transfers	This error occurs when the currency is anything other than `INR` .	Ensure the currency value is `INR` as we support only `INR` for Route transactions.
Keys sent in linked_account_notes must exist in notes	This error occurs when there is a mismatch between the key passed in the `linked_account_notes` array and the key from the `notes` object.	Make sure the key passed in the `linked_account_notes` array always matches the key from the `notes` object.
on_hold_until must be between 946684800 and 4765046400	This error occurs when the time stamp provided for the `on_hold_until` entity is not correct or if it is not between `946684800` and `4765046400` .	Make sure to enter the relevant `on_hold_until` entity time stamp. It should also be within the time `946684800` and `4765046400` .
input is an invalid account_code.	This error occurs when the `account_code` passed is invalid or does not belong to the requested merchant.	Make sure to pass the valid `account_code` .
Transfer cannot be made due to insufficient balance	This error occurs when the total balance is less than or equal to the transfer amount.	Make sure you have enough balance. You can also add funds to the account and then try doing the transfer.
The sum of amount requested for transfer is greater than the captured amount	This error occurs when the total transferred amount exceeds the captured payment amount.	Make sure the transfer amount is less than the captured payment.

Watch Out!

You cannot create transfers on orders which has the partial_payment parameter enabled. Ensure that this parameter is set to 0.
You cannot create transfers on orders for international currencies. Currently, this feature only supports orders created using INR.

Create Transfers from Payments

You can create and capture payments in the regular payments flow using the

Razorpay Checkout

and

Payment APIs

You should perform additional steps to disburse payments using Razorpay Route.

The customer pays the amount using the standard payment flow.
Once the payment is captured, you can initiate a transfer to linked accounts with a transfer API call. You have to pass the details such as account_id and amount.

Hold Settlements For Transfers

When transferring a payment to an account, you can put the transfer settlement on hold indefinitely or until a defined time. You can change these settings anytime via the provided API until the settlement is made. The settlement will not happen until you release it.

To hold the settlement for transfers, you should pass the on_hold and on_hold_until parameters.

The following endpoint transfers a captured payment to one or more linked accounts using account_id. A response is generated on a successful transfer with a collection of transfer entities created for the payment.

Settlement Schedule Override
The settlement schedule defined for the Linked Account takes precedence over the on_hold and on_hold_until functionality. This means that a defined settlement schedule is the minimum time required for the transfer to be settled.

Example: For a T+10 settlement schedule:

If you create a transfer with on_hold: 1 and then release it on T+7 day, the settlement will only go out on T+10 day.
If you create a transfer with on_hold: 1 and on_hold_until: 1491567400 (assume the timestamp 1491567400 corresponds to 7 days after transfer), the on_hold will change to false on T+7 day. The settlement will only go out on T+10 day.

POST

/payments/:id/transfers

Transfers to multiple linked accounts are given in the sample request. The payments transferred to the linked accounts are settled in their respective bank accounts per the pre-defined settlement_period.

{
  "entity": "collection",
  "count": 2,
  "items": [
    {
      "id": "trf_JJD535tJtk6Yy0",
      "entity": "transfer",
      "status": "pending",
      "source": "pay_JGmCgTEa9OTQcX",
      "recipient": "acc_IROu8Nod6PXPtZ",
      "amount": 100,
      "currency": "INR",
      "amount_reversed": 0,
      "notes": {
        "name": "Gaurav Kumar",
        "roll_no": "IEC2011025"
      },
      "linked_account_notes": [
        "roll_no"
      ],
      "on_hold": true,
      "on_hold_until": 1671222870,
      "recipient_settlement_id": null,
      "created_at": 1649933574,
      "processed_at": null,
      "error": {
        "code": null,
        "description": null,
        "reason": null,
        "field": null,
        "step": null,
        "id": "trf_JJD535tJtk6Yy0",
        "source": null,
        "metadata": null
      }
    },
    {
      "id": "trf_JJD536GI6wuz3m",
      "entity": "transfer",
      "status": "pending",
      "source": "pay_JGmCgTEa9OTQcX",
      "recipient": "acc_IRQWUleX4BqvYn",
      "amount": 300,
      "currency": "INR",
      "amount_reversed": 0,
      "notes": {
        "name": "Saurav Kumar",
        "roll_no": "IEC2011026"
      },
      "linked_account_notes": [
        "roll_no"
      ],
      "on_hold": false,
      "on_hold_until": null,
      "recipient_settlement_id": null,
      "created_at": 1649933574,
      "processed_at": null,
      "error": {
        "code": null,
        "description": null,
        "reason": null,
        "field": null,
        "step": null,
        "id": "trf_JJD536GI6wuz3m",
        "source": null,
        "metadata": null
      }
    }
  ]
}

Path Parameter

mandatory

string Unique identifier of the payment on which the transfer must be created.

Request Parameters

transfers

Details regarding the transfer.

account

mandatory

string Unique identifier of the linked account to which the transfer is to be made.

amount

mandatory

integer The amount to be transferred to the linked account. For example, for an amount of ₹200.35, the value of this field should be 20035.

currency

mandatory

string The currency in which the transfer should be made. We support only INR for Route transactions.

notes

linked_account_notes

array List of keys from the notes object which needs to be shown to linked accounts on their Dashboard. For example, "region", "city". Only the keys will be shown, not values.

on_hold

boolean Indicates whether the account settlement for transfer is on hold. Possible values:

1 - Puts the settlement on hold.
0 - Releases the settlement.

on_hold_until

integer Timestamp, in Unix, that indicates until when the settlement of the transfer must be put on hold. If no value is passed, the settlement is put on hold indefinitely.

Response Parameters

Check the response parameters descriptions in the

Transfer entity

parameters table.

Error Response Parameters

Given below is a list of possible errors you may face while creating transfers via Payments.

Error	Cause	Solution
The api key/secret provided is invalid	This error occurs when there is a mismatch between the API credentials passed in the API call and the API credentials generated on the dashboard.	Make sure the API Keys are active and entered correctly. Also, there should not be any whitespaces before or after the keys.
The transfers.0.amount must be at least 100.	This error occurs when the amount is less than the minimum amount. The transaction amount expressed in the currency subunit, such as paise (in INR) should always be greater than or equal to 100.	Make sure the amount is equal to or greater than the minimum amount of ₹100.
The input field is required	This error occurs when a mandatory field is empty.	Make sure to fill in all the mandatory fields.
payment_id is not a valid id	This error occurs when you pass an invalid `payment_id` in the API endpoint.	Make sure to pass a vaild `payment_id` .
The id provided does not exist	This error occurs when there is a miss-match between the API keys via which the transaction was initiated for that particular `payment_id` and the API keys passed in the API call.	Ensure the API keys via which you have accepted the payment for the `payment_id` passed in the API endpoint matches the API keys passed in the API call.
input is an invalid account_code.	This error occurs when the `account_code` passed is invalid or does not belong to the requested merchant.	Make sure to pass the valid `account_code` .
Transfer cannot be made due to insufficient balance	This error occurs when the total balance is less than or equal to the transfer amount.	Make sure you have enough balance. You can also add funds to the account and then try doing the transfer.
The sum of amount requested for transfer is greater than the captured amount	This error occurs when the total transferred amount exceeds the captured payment amount.	Make sure the transfer amount is less than the captured payment.

Direct Transfers

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

Feature Request

This is an on-demand feature. Please raise a request with our
Support team
to get this feature activated on your Razorpay account.
Watch this video to know how to raise a feature enablement request on the Razorpay Dashboard.

Apart from

transferring payments received from customers

, you can also transfer funds to your linked accounts directly from your account balance using the Direct Transfers API.

You can transfer funds directly from your account using the following endpoint.

POST

/transfers

Request Parameters

account

mandatory

string Unique identifier of the linked account to which the transfer must be made.

amount

mandatory

integer The amount (in paise) to be transferred to the linked account. For example, for an amount of ₹200.35, the value of this field should be 20035.

currency

mandatory

string The currency used in the transaction. We support only INR for Route transactions.

notes

optional

Response Parameters

Check the response parameters descriptions in the

Transfer entity

parameters table.

Error Response Parameters

Given below is a list of possible errors you may face while creating a Direct Transfer.

Error	Cause	Solution
The api key/secret provided is invalid	This error occurs when there is a mismatch between the API credentials passed in the API call and the API credentials generated on the dashboard.	Make sure the API Keys are active and entered correctly. Also, there should not be any whitespaces before or after the keys.
The transfers.0.amount must be at least 100.	This error occurs when the amount is less than the minimum amount. The transaction amount expressed in the currency subunit, such as paise (in INR) should always be greater than or equal to 100.	Make sure the amount is equal to or greater than the minimum amount of ₹100.
The input field is required	This error occurs when a mandatory field is empty.	Make sure to fill in all the mandatory fields.

Idempotent Request

Idempotency allows you to safely retry or send the same request multiple times without fear of repeating the transfer request more than once.

For example, when you try to create a transfer, in some cases due to network downtimes, you may not get a response from our servers. As a consequence, you will not be aware of the transfer id or its state. In such cases, you can safely retry the transaction using the same idempotency key without risk of double-payout or duplication.

To make a transfer request idempotent, add the header X-Transfer-Idempotency to the request and pass an idempotency key against it. The idempotency key (4-36 characters) can contain alphabets, numbers, hyphens, underscores and space only. For example, fbdabb70-9548-4cfe-8da1-c9bbf39e96b0.

Watch Out!
Currently, idempotency is supported only on the Direct Transfers API.

Handy Tips

When retrying a request, the request body must be the same as the first request for idempotency to work. A different payload will be rejected as a BAD_REQUEST.
The idempotency key in retries must be the same as the original request.
Use unique idempotency keys for each unique request.
If we receive another request while the first one is in process, we will send a 409 error code. You can retry if you get this error code.

Fetch Transfers for a Payment

The following endpoint fetches the collection of all transfers created on a specific Payment ID.

GET

/payments/:id/transfers

{
  "entity": "collection",
  "count": 2,
  "items": [
    {
      "id": "trf_JJD535tJtk6Yy0",
      "entity": "transfer",
      "status": "processed",
      "source": "pay_JGmCgTEa9OTQcX",
      "recipient": "acc_IROu8Nod6PXPtZ",
      "amount": 100,
      "currency": "INR",
      "amount_reversed": 0,
      "fees": 1,
      "tax": 0,
      "notes": {
        "name": "Gaurav Kumar",
        "roll_no": "IEC2011025"
      },
      "linked_account_notes": [
        "roll_no"
      ],
      "on_hold": true,
      "on_hold_until": 1671222870,
      "settlement_status": "on_hold",
      "recipient_settlement_id": null,
      "created_at": 1649933574,
      "processed_at": 1649933579,
      "error": {
        "code": null,
        "description": null,
        "reason": null,
        "field": null,
        "step": null,
        "id": "trf_JJD535tJtk6Yy0",
        "source": null,
        "metadata": null
      }
    },
    {
      "id": "trf_JJD536GI6wuz3m",
      "entity": "transfer",
      "status": "processed",
      "source": "pay_JGmCgTEa9OTQcX",
      "recipient": "acc_IRQWUleX4BqvYn",
      "amount": 300,
      "currency": "INR",
      "amount_reversed": 0,
      "fees": 1,
      "tax": 0,
      "notes": {
        "name": "Saurav Kumar",
        "roll_no": "IEC2011026"
      },
      "linked_account_notes": [
        "roll_no"
      ],
      "on_hold": false,
      "on_hold_until": null,
      "settlement_status": "pending",
      "recipient_settlement_id": null,
      "created_at": 1649933574,
      "processed_at": 1649933579,
      "error": {
        "code": null,
        "description": null,
        "reason": null,
        "field": null,
        "step": null,
        "id": "trf_JJD536GI6wuz3m",
        "source": null,
        "metadata": null
      }
    }
  ]
}

Path Parameter

mandatory

string Unique identifier of the Payment for which transfers must be retrieved.

Response Parameters

Check the response parameters descriptions in the

Transfer entity

parameters table.

Once the settlement against the transfer is processed, a webhook notification settlement.processed is sent which contains a recipient_settlement_id. Know more about

sample webhook payloads

Error Response Parameters

Given below is a list of possible errors you may face while fetching transfers for a payment.

Error	Cause	Solution
The api key/secret provided is invalid	This error occurs when there is a mismatch between the API credentials passed in the API call and the API credentials generated on the dashboard.	Make sure the API Keys are active and entered correctly. Also, there should not be any whitespaces before or after the keys.
payment_id is not a valid id	This error occurs when you pass an invalid `payment_id` in the API endpoint.	Make sure to pass a vaild `payment_id` .

Fetch Transfer for an Order

The following endpoint fetches the collection of all transfers created on a specific Order ID.

GET

/orders/:id/?expand[]=transfers&status

{
  "id": "order_JJCYnu3hipocHz",
  "entity": "order",
  "amount": 2000,
  "amount_paid": 0,
  "amount_due": 2000,
  "currency": "INR",
  "receipt": null,
  "offer_id": null,
  "status": "created",
  "attempts": 0,
  "notes": [],
  "created_at": 1649931742,
  "transfers": {
    "entity": "collection",
    "count": 2,
    "items": [
      {
        "id": "trf_JJCYnw77tqUT9r",
        "entity": "transfer",
        "status": "created",
        "source": "order_JJCYnu3hipocHz",
        "recipient": "acc_IRQWUleX4BqvYn",
        "amount": 1000,
        "currency": "INR",
        "amount_reversed": 0,
        "fees": 0,
        "tax": null,
        "notes": {
          "branch": "Acme Corp Bangalore North",
          "name": "Gaurav Kumar"
        },
        "linked_account_notes": [
          "branch"
        ],
        "on_hold": true,
        "on_hold_until": 1671222870,
        "settlement_status": null,
        "recipient_settlement_id": null,
        "created_at": 1649931742,
        "processed_at": null,
        "error": {
          "code": null,
          "description": null,
          "reason": null,
          "field": null,
          "step": null,
          "id": "trf_JJCYnw77tqUT9r",
          "source": null,
          "metadata": null
        }
      },
      {
        "id": "trf_JJCYnxe5GV19Kk",
        "entity": "transfer",
        "status": "created",
        "source": "order_JJCYnu3hipocHz",
        "recipient": "acc_IROu8Nod6PXPtZ",
        "amount": 1000,
        "currency": "INR",
        "amount_reversed": 0,
        "fees": 0,
        "tax": null,
        "notes": {
          "branch": "Acme Corp Bangalore South",
          "name": "Saurav Kumar"
        },
        "linked_account_notes": [
          "branch"
        ],
        "on_hold": false,
        "on_hold_until": null,
        "settlement_status": null,
        "recipient_settlement_id": null,
        "created_at": 1649931742,
        "processed_at": null,
        "error": {
          "code": null,
          "description": null,
          "reason": null,
          "field": null,
          "step": null,
          "id": "trf_JJCYnxe5GV19Kk",
          "source": null,
          "metadata": null
        }
      }
    ]
  }
}

Path Parameter

mandatory

string Unique identifier of the Order for which transfers must be retrieved.

Query Parameter

expand

mandatory

array Used to retrieve details regarding the transfers initiated via an order. Supported value is transfers.

status

optional

string Status of the transfer.

Descriptions for the optional query parameters are present in the

Pagination & Rate Limiting

documentation.

Response Parameters

string Unique identifier of the Order created.

entity

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

amount

integer The Order amount, in paise. For example, for an amount of ₹299.35, the value of this field should be 29935.

amount_paid

integer The amount paid against the Order.

amount_due

integer The amount pending against the Order.

currency

string The currency in which the order should be created. We support only INR for Route transactions.

receipt

string Unique identifier that you can use for internal reference.

status

string The status of the Order. Below are the possible values:

created
attempted
paid

notes

created_at

integer Timestamp in Unix. This indicates the time of the order created.

transfers

Details regarding the transfer.

string Unique identifier of the transfer.

recipient

string Unique identifier of the linked account to which the transfer is to be made.

transfer_status

string The status of the transfer. Possible values are:

created
pending
processed
failed
reversed
partially_reversed

settlement_status

string The status of the settlement. Possible values are:

pending
on_hold
settled

amount

integer The amount to be transferred to the linked account, in paise. For example, for an amount of ₹200.35, the value of this field should be 20035.This amount cannot exceed the order amount.

currency

string The currency in which the transfer should be made. We support only INR for Route transactions.

notes

linked_account_notes

array List of keys from the notes object which needs to be shown to linked accounts on their Dashboard. For example, "region", "city". Only the keys will be shown, not values.

on_hold

boolean Indicates whether the account settlement for transfer is on hold. Possible values:

1 - Puts the settlement on hold.
0 - Releases the settlement.

on_hold_until

integer Timestamp, in Unix, that indicates until when the settlement of the transfer must be put on hold. If no value is passed, the settlement is put on hold indefinitely.

error

Provides error details that may occur during transfers.

code

string Type of the error.

description

string Error description.

field

string Name of the parameter in the API request that caused the error.

source

string The point of failure in the specific operation. For example, customer, business and so on.

step

string The stage where the transaction failure occurred. Stages can be different depending on the payment method used to make the transaction.

reason

string The exact error reason. It can be handled programmatically.

Error Response Parameters

Given below is a list of possible errors you may face while fetching transfers for an order.

Error	Cause	Solution
The api key/secret provided is invalid	This error occurs when there is a mismatch between the API credentials passed in the API call and the API credentials generated on the dashboard.	Make sure the API Keys are active and entered correctly. Also, there should not be any whitespaces before or after the keys.
order_id is not a valid id	This error occurs when you pass an invalid `order_id` in the API endpoint.	Make sure to pass a vaild `order_id` .

Fetch a Transfer

The following endpoint fetches details of a specific transfer.

GET

/transfers/:id

Path Parameter

mandatory

string Unique identifier of the transfer for which details must be fetched.

Response Parameters

Check the response parameters descriptions in the

Transfer entity

parameters table.

Error Response Parameters

Given below is a list of possible errors you may face while fetching a transfer.

Error	Cause	Solution
The api key/secret provided is invalid	This error occurs when there is a mismatch between the API credentials passed in the API call and the API credentials generated on the dashboard.	Make sure the API Keys are active and entered correctly. Also, there should not be any whitespaces before or after the keys.
transfer_id is not a valid id	This error occurs when you pass an invalid `transfer_id` in the API endpoint.	Make sure to pass a vaild `transfer_id` .

Fetch Transfers for a Settlement

The following endpoint retrieves the collection of all transfers made for a particular recipient_settlement_id.

GET

/transfers?recipient_settlement_id

{
  "entity": "collection",
  "count": 1,
  "items": [
    {
      "id": "trf_HWjmkReRGPhguR",
      "entity": "transfer",
      "status": "processed",
      "source": "pay_HWjY9DZSMsbm5E",
      "recipient": "acc_HWjl1kqobJzf4i",
      "amount": 1000,
      "currency": "INR",
      "amount_reversed": 0,
      "fees": 3,
      "tax": 0,
      "notes": [],
      "linked_account_notes": [],
      "on_hold": false,
      "on_hold_until": null,
      "settlement_status": "settled",
      "recipient_settlement_id": "setl_HYIIk3H0J4PYdX",
      "created_at": 1625812996,
      "processed_at": 1625812996,
      "error": {
        "code": null,
        "description": null,
        "reason": null,
        "field": null,
        "step": null,
        "id": "trf_HWjmkReRGPhguR",
        "source": null,
        "metadata": null
      }
    }
  ]
}

Query Parameter

recipient_settlement_id

mandatory

string Unique identifier of a settlement obtained from the settlement.processed webhook payload.

Descriptions for the optional query parameters are present in the

Pagination & Rate Limiting

documentation.

Response Parameters

Check the response parameters descriptions in the

Transfer entity

parameters table.

Error Response Parameters

Given below is a list of possible errors you may face while fetching transfers for a settlement.

Error	Cause	Solution
The api key/secret provided is invalid	This error occurs when there is a mismatch between the API credentials passed in the API call and the API credentials generated on the dashboard.	Make sure the API Keys are active and entered correctly. Also, there should not be any whitespaces before or after the keys.

Fetch Settlement Details

The following endpoint fetches details of settlements made to linked accounts.

GET

/transfers?expand[]=recipient_settlement

You should append ?expand[]=recipient_settlement as the query parameter to the fetch transfer request. This would return a settlement entity and the transfer entity.

{
  "entity": "collection",
  "count": 2,
  "items": [
    {
      "id": "trf_JCu3ZstilY6Whi",
      "entity": "transfer",
      "status": "failed",
      "source": "pay_HWjY9DZSMsbm5E",
      "recipient": "acc_CNo3jSI8OkFJJJ",
      "amount": 100,
      "currency": "INR",
      "amount_reversed": 0,
      "fees": 0,
      "tax": null,
      "notes": {
        "name": "Saurav Kumar",
        "roll_no": "IEC2011026"
      },
      "linked_account_notes": [
        "roll_no"
      ],
      "on_hold": false,
      "on_hold_until": null,
      "settlement_status": null,
      "recipient_settlement_id": null,
      "recipient_settlement": null,
      "created_at": 1648556539,
      "processed_at": 1648556543,
      "error": {
        "code": "BAD_REQUEST_TRANSFER_INSUFFICIENT_BALANCE",
        "description": "Account does not have sufficient balance to carry out transfer operation",
        "reason": "insufficient_account_balance",
        "field": "amount",
        "step": "transfer_processing",
        "id": "trf_JCu3ZstilY6Whi",
        "source": null,
        "metadata": null
      }
    },
    {
      "id": "trf_JCu3ZsTVSuy7oN",
      "entity": "transfer",
      "status": "failed",
      "source": "pay_HWjY9DZSMsbm5E",
      "recipient": "acc_CPRsN1LkFccllA",
      "amount": 100,
      "currency": "INR",
      "amount_reversed": 0,
      "fees": 0,
      "tax": null,
      "notes": {
        "name": "Gaurav Kumar",
        "roll_no": "IEC2011025"
      },
      "linked_account_notes": [
        "roll_no"
      ],
      "on_hold": true,
      "on_hold_until": 1671222870,
      "settlement_status": null,
      "recipient_settlement_id": null,
      "recipient_settlement": null,
      "created_at": 1648556539,
      "processed_at": 1648556543,
      "error": {
        "code": "BAD_REQUEST_TRANSFER_INSUFFICIENT_BALANCE",
        "description": "Account does not have sufficient balance to carry out transfer operation",
        "reason": "insufficient_account_balance",
        "field": "amount",
        "step": "transfer_processing",
        "id": "trf_JCu3ZsTVSuy7oN",
        "source": null,
        "metadata": null
      }
    }
  ]
}

Query Parameter

expand

mandatory

string Used to retrieve settlement entity along with transfer entity. Supported value is recipient_settlement.

Descriptions for the optional query parameters are present in the

Pagination & Rate Limiting

documentation.

Response Parameters

Check the response parameters descriptions in the

Transfer entity

parameters table.

Error Response Parameters

Given below is a list of possible errors you may face while fetching settlement details.

Error	Cause	Solution
The api key/secret provided is invalid	This error occurs when there is a mismatch between the API credentials passed in the API call and the API credentials generated on the dashboard.	Make sure the API Keys are active and entered correctly. Also, there should not be any whitespaces before or after the keys.

Handy Tips

If you get null as an API response, an invalid recipient_settlement_id was passed. Ensure to pass a valid recipient_settlement_id, and it belongs to the Linked Account.

Fetch Payments of a Linked Account

The following endpoint fetches a list of all the payments received by a linked account.

GET

/payments/

For this, you should send the Linked Account ID in the X-Razorpay-Account API request header, as shown in the cURL example.

{
  "entity": "collection",
  "count": 2,
  "items": [
    {
      "id": "pay_JJCqynf4fQS0N1",
      "entity": "payment",
      "amount": 10000,
      "currency": "INR",
      "status": "captured",
      "order_id": "order_JJCqnZG8f3754z",
      "invoice_id": null,
      "international": false,
      "method": "netbanking",
      "amount_refunded": 0,
      "refund_status": null,
      "captured": true,
      "description": "#JJCqaOhFihfkVE",
      "card_id": null,
      "bank": "YESB",
      "wallet": null,
      "vpa": null,
      "email": "john.example@example.com",
      "contact": "+919820958250",
      "notes": [],
      "fee": 236,
      "tax": 36,
      "error_code": null,
      "error_description": null,
      "error_source": null,
      "error_step": null,
      "error_reason": null,
      "acquirer_data": {
        "bank_transaction_id": "2118867"
      },
      "created_at": 1649932775
    },
    {
      "id": "pay_JHAe1Zat55GbZB",
      "entity": "payment",
      "amount": 5000,
      "currency": "INR",
      "status": "captured",
      "order_id": "order_IluGWxBm9U8zJ8",
      "invoice_id": null,
      "international": false,
      "method": "netbanking",
      "amount_refunded": 0,
      "refund_status": null,
      "captured": true,
      "description": "Test Transaction",
      "card_id": null,
      "bank": "KKBK",
      "wallet": null,
      "vpa": null,
      "email": "gaurav.kumar@example.com",
      "contact": "+919000090000",
      "notes": {
        "address": "Razorpay Corporate Office"
      },
      "fee": 118,
      "tax": 18,
      "error_code": null,
      "error_description": null,
      "error_source": null,
      "error_step": null,
      "error_reason": null,
      "acquirer_data": {
        "bank_transaction_id": "7003347"
      },
      "created_at": 1649488316
    }
  ]
}

Response Parameters

string Unique identifier of the payment.

entity

string Indicates the type of entity.

amount

string The payment amount represented in the smallest unit of the currency passed. For example, for an amount of ₹200.35, the value of this field should be 20035.

currency

string The currency in which the payment is made. We support only INR for Route transactions.

status

string The status of the payment. Possible values:

created
authorized
captured
refunded
failed

method

string The payment method used for making the payment. Here, it will be transfer.

order_id

string Unique identifier of the order associated with the payment.

description

string Description of the payment, if any.

refund_status

string The refund status of the payment. Possible values include:
- null
- partial
- full.

amount_refunded

integer The amount refunded in the smallest unit of the currency passed. For example, if the amount_refunded is 100, then it translates to 100 paise, that is ₹1. Only INR is supported.

captured

boolean Indicates whether the payment has been captured.

string Customer email address used for the payment.

contact

string Customer contact number used for the payment.

fee

integer Fee (including GST) charged by Razorpay.

tax

integer GST charged for the payment.

error_code

string Code for the error that occurred during payment. For example, BAD_GATEWAY_ERROR.

error_description

string Description of the error that occurred during payment.

notes

created_at

integer Timestamp, in Unix, on which the payment was created.

Error Response Parameters

Given below is a list of possible errors you may face while fetching payments of a Linked Account.

Error	Cause	Solution
The api key/secret provided is invalid	This error occurs when there is a mismatch between the API credentials passed in the API call and the API credentials generated on the dashboard.	Make sure the API Keys are active and entered correctly. Also, there should not be any whitespaces before or after the keys.
The id provided does not exist	This error occurs when the linked account is invalid or does not belong to the requested merchant.	Ensure the Linked Account is valid and belongs to the requested merchant.

Refunds and Reversals

You can refund payments to customers and reverse transfers made to linked accounts using the following APIs:

Refund Payments and Reverse Transfer from a Linked Account

Payment can be refunded to a customer using Refunds API.

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

You can automate reversals with the reverse_all parameter in the following refund scenarios:

Full refund
Partial refund for a payment transferred to a single account.

Watch Out!
For partial refunds on a payment transferred to multiple accounts, the reverse_all parameter cannot be applied since Razorpay cannot determine which transfer to reverse partially. You will have to use the transfer reversal API to reverse this payment.

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

The following endpoint creates refunds on a particular payment_id.

POST

/payments/:id/refund

Route Transfers