Razorpay Route enables you to split payments received using the Razorpay Payment Gateway or other products (such as Payment Links, Payment Pages, Invoices, Subscriptions and Smart Collect) and transfer the funds to your vendors.

You can onboard a vendor and manage their linked account on your Razorpay Dashboard.

Refer to the Route Product Documents before proceeding with the below APIs.

The following details are required to create a linked account:

Primary Details	Bank Details
Linked Account Name Type Contact Number	Account Number Account Type IFSC Beneficiary Name

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

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

Transfers🔗

You can transfer funds to your linked accounts using the Razorpay Route Transfer APIs. Know more about transfers and 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 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 on consecutive days. There will be maximum of 3 retries.
Transfer via Payments
You can initiate a transfer once the payment has been received from the customer.
Direct Transfer
You can initiate a transfer directly from existing funds in your Razorpay account.

Watch Out!
Direct Transfers is an on-demand feature. Please raise a request with our Support team to get this feature activated on your Razorpay account.

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 attributes of the transfer entity are listed below:

id

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.

 Response
Copy{
   "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🔗

 Curl PHP Node.JS Python Go Response
Copycurl -X POST https://api.razorpay.com/v1/orders \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-H 'content-type: application/json'
-d '{
  "amount": 2000,
  "currency": "INR",
  "transfers": [
    {
      "account": "acc_IRQWUleX4BqvYn",
      "amount": 1000,
      "currency": "INR",
      "notes": {
        "branch": "Acme Corp Bangalore North",
        "name": "Gaurav Kumar"
      },
      "linked_account_notes": [
        "branch"
      ],
      "on_hold": 1,
      "on_hold_until": 1671222870
    },
    {
      "account": "acc_IROu8Nod6PXPtZ",
      "amount": 1000,
      "currency": "INR",
      "notes": {
        "branch": "Acme Corp Bangalore South",
        "name": "Saurav Kumar"
      },
      "linked_account_notes": [
        "branch"
      ],
      "on_hold": 0
    }
  ]
}'

Copy$api = new Api($key_id, $secret);

$api->order->create(array('amount' => 2000,'currency' => 'INR','transfers' => array(array('account' => 'acc_CPRsN1LkFccllA','amount' => 1000,'currency' => 'INR','notes' => array('branch' => 'Acme Corp Bangalore North','name' => 'Gaurav Kumar'),'linked_account_notes' => array('branch'),'on_hold' => 1,'on_hold_until' => 1671222870),array('account' => 'acc_CNo3jSI8OkFJJJ','amount' => 1000,'currency' => 'INR','notes' => array('branch' => 'Acme Corp Bangalore South','name' => 'Saurav Kumar'),'linked_account_notes' => array('branch'),'on_hold' => 0))));

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.orders.create({
  amount: 2000,
  currency: "INR",
  transfers: [
    {
      account: "acc_CPRsN1LkFccllA",
      amount: 1000,
      currency: "INR",
      notes: {
        branch: "Acme Corp Bangalore North",
        name: "Gaurav Kumar"
      },
      linked_account_notes: [
        "branch"
      ],
      on_hold: 1,
      on_hold_until: 1671222870
    },
    {
      account: "acc_CNo3jSI8OkFJJJ",
      amount: 1000,
      currency: "INR",
      notes: {
        branch: "Acme Corp Bangalore South",
        name: "Saurav Kumar"
      },
      linked_account_notes: [
        "branch"
      ],
      on_hold: 0
    }
  ]
})

Copyclient = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.order.create({
   "amount":2000,
   "currency":"INR",
   "transfers":[
      {
         "account":"acc_CPRsN1LkFccllA",
         "amount":1000,
         "currency":"INR",
         "notes":{
            "branch":"Acme Corp Bangalore North",
            "name":"Gaurav Kumar"
         },
         "linked_account_notes":[
            "branch"
         ],
         "on_hold":1,
         "on_hold_until":1671222870
      },
      {
         "account":"acc_CNo3jSI8OkFJJJ",
         "amount":1000,
         "currency":"INR",
         "notes":{
            "branch":"Acme Corp Bangalore South",
            "name":"Saurav Kumar"
         },
         "linked_account_notes":[
            "branch"
         ],
         "on_hold":0
      }
   ]
})

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

data:= map[string]interface{}{
  "amount": 2000,
  "currency": "INR",
  "transfers": []interface{}{
    map[string]interface{}{
      "account": "acc_IRQWUleX4BqvYn",
      "amount": 100,
      "currency": "INR",
      "notes": map[string]interface{}{
        "branch": "Acme Corp Bangalore North",
        "name": "Gaurav Kumar",
      },
      "linked_account_notes": []string{
        "branch",
      },
      "on_hold": true,
      "on_hold_until": 1671222870,
      },
  },
}

Copy{
  "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
      }
    }
  ]
}

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.

/orders

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🔗

id

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.

id

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.

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🔗

 Curl PHP Node.JS Python Go Response
Copycurl -X POST https://api.razorpay.com/v1/payments/pay_E8JR8E0XyjUSZd/transfers \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-H 'content-type: application/json'
-d '{
  "transfers": [
    {
      "account": "acc_IROu8Nod6PXPtZ",
      "amount": 100,
      "currency": "INR",
      "notes": {
        "name": "Gaurav Kumar",
        "roll_no": "IEC2011025"
      },
      "linked_account_notes": [
        "roll_no"
      ],
      "on_hold": true,
      "on_hold_until": 1671222870
    },
    {
      "account": "acc_IRQWUleX4BqvYn",
      "amount": 300,
      "currency": "INR",
      "notes": {
        "name": "Saurav Kumar",
        "roll_no": "IEC2011026"
      },
      "linked_account_notes": [
        "roll_no"
      ],
      "on_hold": false
    }
  ]
}'

Copy$api = new Api($key_id, $secret);

$api->payment->fetch($paymentId)->transfer(array('transfers' => array('account'=> $accountId, 'amount'=> '1000', 'currency'=>'INR', 'notes'=> array('name'=>'Gaurav Kumar', 'roll_no'=>'IEC2011025'), 'linked_account_notes'=>array('branch'), 'on_hold'=>'1', 'on_hold_until'=>'1671222870')));

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.payments.transfer(paymentId,{
   "transfers": [
    {
      "account": 'acc_HgzcrXeSLfNP9U',
      "amount": 100,
      "currency": "INR",
      "notes": {
        "name": "Gaurav Kumar",
        "roll_no": "IEC2011025"
      },
      "linked_account_notes": [
        "branch"
      ],
      "on_hold": 1,
      "on_hold_until": 1671222870
    }
  ]
 })

Copyclient = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.payment.fetch({
   "transfers":{
      "amount":1000,
      "currency":"INR",
      "notes":{
         "name":"Gaurav Kumar",
         "roll_no":"IEC2011025"
      },
      "linked_account_notes":[
         "branch"
      ],
      "on_hold":1,
      "on_hold_until":1671222870
   }
})

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

data:= map[string]interface{}{
  "transfers": []interface{}{
    map[string]interface{}{
      "account": "acc_HjVXbtpSCIxENR",
      "amount": 100,
      "currency": "INR",
      "notes": map[string]interface{}{
        "name": "Gaurav Kumar",
        "roll_no": "IEC2011025",
      },
      "linked_account_notes": []string{
        "roll_no",
      },
      "on_hold": true,
      "on_hold_until": 1671222870,
    },
  },
}

Copy{
  "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
      }
    }
  ]
}

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

To disburse payments using Razorpay Route, there is an additional step in the payment flow called transfers which is described below:

The customer pays the amount via normal payment flow.
Once the payment is captured, you can initiate a transfer to linked accounts with a transfer API call. You have to specify the details of the account_id and amount.

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

/payments/:id/transfers

In the sample request given, transfers to multiple linked accounts are specified. The payments transferred to the linked accounts will be settled to their respective bank accounts as per the pre-defined settlement_period.

Path Parameter🔗

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

The response parameters are same as the transfer entity parameters.

Direct Transfers🔗

 Curl PHP Node.JS Python Go Response
Copycurl -X POST https://api.razorpay.com/v1/transfers \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-H 'content-type: application/json' \
-d '{
  "account": "acc_CPRsN1LkFccllA",
  "amount": 100,
  "currency": "INR"
}'

Copy$api = new Api($key_id, $secret);

$api->transfer->create(array('account' => $accountId, 'amount' => 500, 'currency' => 'INR'));

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.transfers.create({
  "amount": 500,
  "currency": "INR"
})

Copyclient = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.transfer.create({
   "amount":500,
   "currency":"INR"
})

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

data:= map[string]interface{}{
  "account": "<accountId>",
  "amount": 100,
  "currency": "INR",
}
body, err := client.Transfer.Create(data, nil)

Copy{
   "id":"trf_E9utgtfGTcpcmm",
   "entity":"transfer",
   "transfer_status":"pending",
   "settlement_status":null,
   "source":"acc_CJoeHMNpi0nC7k",
   "recipient":"acc_CPRsN1LkFccllA",
   "amount":100,
   "currency":"INR",
   "amount_reversed":0,
   "notes":[
      
   ],
   "fees":1,
   "tax":0,
   "on_hold":false,
   "on_hold_until":null,
   "recipient_settlement_id":null,
   "created_at":1580219046,
   "linked_account_notes":[
      
   ],
   "processed_at":null,
   "error":{
      "code":null,
      "description":null,
      "field":null,
      "source":null,
      "step":null,
      "reason":null
   }
}

Watch Out!
Direct Transfers is an on-demand feature. Please raise a request with our Support team to get this feature activated on your Razorpay account.

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.

/transfers

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

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

Fetch Transfers for a Payment🔗

Use this endpoint to fetch the collection of all transfers created on a specific Payment ID.

/payments/:id/transfers

 Curl PHP Node.JS Python Go Response
Copycurl -X GET https://api.razorpay.com/v1/payments/pay_JGmCgTEa9OTQcX/transfers \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \ 

Copy$api = new Api($key_id, $secret);

$api->payment->fetch('payment')->transfers();

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.payments.fetchTransfer(paymentId)

Copyclient = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.payment.transfers(paymentId)

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

body, err := client.Payment.Transfers("<paymentId>", nil, nil)

Copy{
  "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🔗

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

Response Parameters🔗

id

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

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.

Once the settlement against the transfer is processed, a webhook settlement.processed is sent which contains a recipient_settlement_id. Refer the sample webhook payload for more information.

Fetch Transfer for an Order🔗

Use this endpoint to fetch the collection of all transfers created on a specific Order ID.

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

 Curl PHP Node.JS Python Go Response
Copycurl -X GET https://api.razorpay.com/v1/orders/order_JJCYnu3hipocHz/?expand[]=transfers \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \ 

Copy$api = new Api($key_id, $secret);

$api->order->fetch($orderId)->transfers(array('expand[]'=>'transfers'));

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.orders.fetchTransferOrder(orderId)

Copyclient = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.order.fetch({
   "expand[]":"transfers"
})

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

data := map[string]interface{}{
  "expand[]": "transfers",
}
body, err := client.Order.Fetch("<orderId>", data, nil)

Copy{
  "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🔗

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

Response Parameters🔗

id

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.

id

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.

Fetch a Transfer🔗

You can use the following endpoint to fetch details of a specific transfer.

/transfers/:id

 Curl PHP Node.JS Python Go Response
Copycurl -X GET https://api.razorpay.com/v1/transfers/trf_JJD536GI6wuz3m \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \ 

Copy$api = new Api($key_id, $secret);

$api->transfer->fetch($transferId);

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.transfers.fetch(transferId)

Copyclient = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.transfer.fetch(transferId)

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

body, err := client.Transfer.Fetch("<transferId>", nil, nil)

Copy{
  "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🔗

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

Fetch Transfers for a Settlement🔗

You can use the following endpoint to retrieve the collection of all transfers made for a particular recipient_settlement_id.

/transfers

 Curl PHP Node.JS Python Go Response
Copycurl -X GET https://api.razorpay.com/v1/transfers?recipient_settlement_id=setl_HYIIk3H0J4PYdX \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \  

Copy$api = new Api($key_id, $secret);

$api->transfer->all(array('recipient_settlement_id'=> $recipientSettlementId));

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.transfers.all({
   recipient_settlement_id :  recipientSettlementId
})

Copyclient = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.transfer.all({
   "recipient_settlement_id":"recipientSettlementId"
})

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

data:= map[string]interface{}{
  "recipient_settlement_id": "<recipientSettlementId>",
}
body, err := client.Transfer.All(data, nil)

Copy{
  "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.

Fetch Settlement Details🔗

You can use the following endpoint to fetch the details of settlements made to linked accounts.

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

/transfers?expand[]=recipient_settlement

 Curl PHP Node.JS Python Go Response
Copycurl -X GET https://api.razorpay.com/v1/transfers?expand[]=recipient_settlement \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \ 

Copy$api = new Api($key_id, $secret);

$api->transfer->all(array('expand[]'=> 'recipient_settlement'));

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.transfers.all({
  expand[] = 'recipient_settlement'  
})

Copyclient = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.transfer.all({
   "expand[]":"recipient_settlement"
})

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

data:= map[string]interface{}{
  "expand[]": "recipient_settlement",
}
body, err := client.Transfer.All(data, nil)

Copy{
  "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.

Response Parameters🔗

id

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. This can be useful for storing additional information about the entity. A maximum of 15 key-value pairs, each of 256 characters (maximum), are supported.

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.

recipient_settlement_id

string Unique identifier of the settlement.

recipient_settlement

array

id: string Unique identifier of the settlement received by the linked account.
entity: string Indicates the type of entity. Here, it is settlement.
amount: string The settlement amount represented in the smallest unit of the currency passed.
status: string The status of the settlement. Possible values: -processed - The settlement process was successful. -failed - The settlement process failed.
fee: integer Fee (including GST) charged by Razorpay.
tax: integer GST charged for the payment.
utr: string Unique identifier received for the settlement from the bank.
created_at: integer Timestamp, in Unix, at which the settlement was created.

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.

created_at

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

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.

Fetch Payments of a Linked Account🔗

You can use the following endpoint to fetch a list of all the payments received by a linked account.

/payments/

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

 Curl PHP Node.JS Python Go Response
Copycurl -X GET https://api.razorpay.com/v1/payments \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-H 'X-Razorpay-Account: acc_IRQWUleX4BqvYn' \

Copy$api = new Api($key_id, $secret);

$api->payment->all(array('X-Razorpay-Account'=> $linkedAccountId));

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.payments.all({
  'X-Razorpay-Account':  linkedAccountId
})

Copyclient = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.payment.all({
   "X-Razorpay-Account":"linkedAccountId"
})
Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

extraHeaders:= map[string]string{
  "X-Razorpay-Account": "<linkedAccountId>",
}
body, err := client.Payment.All(nil, extraHeaders)

Copy{
  "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": "+919999999999",
      "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🔗

id

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.

email

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.

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🔗

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

You can use the following endpoint to create refunds on a particular payment_id.

/payments/:id/refund

When refunding a payment that has transfers, 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 process will recover the amount from the linked account for every transfer made on the payment before processing the refund to the customer.

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.

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

 Curl PHP Node.JS Python Go Response
Copycurl -X POST  https://api.razorpay.com/v1/payments/pay_JJCqynf4fQS0N1/refund \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-H 'content-type: application/json'
-d '{
  "amount": 100,
  "reverse_all": 1
}'

Copy$api = new Api($key_id, $secret);

$api->payment->fetch($paymentId)->refund(array('amount'=> '100','reverse_all'=>'1'));

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.payments.refund(paymentId,{
    amount : 100,
    reverse_all : 1
})

Copyclient = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.payment.refund(paymentId, {"amount": 100, "reverse_all": 1})

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

data:= map[string]interface{}{
  "reverse_all": 1,
}
body, err := client.Payment.Refund("<paymentId>", <amount>, data, nil)

Copy{
  "id": "rfnd_JJFNlNXPHY640A",
  "entity": "refund",
  "amount": 100,
  "currency": "INR",
  "payment_id": "pay_JJCqynf4fQS0N1",
  "notes": [],
  "receipt": null,
  "acquirer_data": {
    "arn": null
  },
  "created_at": 1649941680,
  "batch_id": null,
  "status": "processed",
  "speed_processed": "normal",
  "speed_requested": "normal"
}

Path Parameter🔗

id mandatory: string A unique identifier of the payment that should be refunded.

Request Parameters🔗

amount mandatory

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

reverse_all optional

boolean Reverses transfer made to a linked account. Possible values:

1 - Reverses transfer made to a linked account.
0 - Does not reverse transfer made to a linked account.

Response Parameters🔗

id: string Unique identifier of the refund.
entity: string Indicates the type of entity. Here, it is refund.
amount: integer The amount of refund in the smallest unit of currency. For example, for an amount of ₹200.35, the value of this field should be 20035.
currency: string The currency of refund. Currently, only INR is supported.
payment_id: string Unique identifier of the payment for which this refund has been requested.
created_at: integer Timestamp, in Unix, of refund creation.
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.
receipt: string Unique identifier that you can use for internal reference.
acquirer_data: array A dynamic array consisting of a unique reference number (either RRN, ARN or UTR) that is provided by the banking partner when a refund is processed. This reference number can be used by the customer to track the status of the refund with the bank.

Reverse Transfers from all Linked Accounts🔗

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

You can use the following endpoint to create reversals on a particular transfer_id.

/transfers/:id/reversals

This request creates a reversal entity and reverses the funds transferred from your account to the linked account. Here, the amount specified is debited from the linked account balance and credited to your balance.

Partial reversals are also supported, and you can create multiple reversals on a transfer_id. If you do not provide the amount parameter in the request, then the entire amount of the transfer is reversed.

 Curl PHP Node.JS Python Go Response
Copycurl -X POST https://api.razorpay.com/v1/transfers/trf_EAznuJ9cDLnF7Y/reversals \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-H 'content-type: application/json'
-d '{
  "amount": 100
}'

Copy$api = new Api($key_id, $secret);

$api->transfer->fetch($transferId)->reverse(array('amount'=>'100'));

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.transfers.reverse(transferId,{
    amount:100
})

Copyclient = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.transfer.reverse(transferId, {"amount": 100})

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

data:= map[string]interface{}{
  "amount": 100,
}
body, err := client.Transfer.Reverse("<transferId>", data, nil)

Copy{
  "id": "rvrsl_EB0BWgGDAu7tOz",
  "entity": "reversal",
  "transfer_id": "trf_EAznuJ9cDLnF7Y",
  "amount": 100,
  "fee": 0,
  "tax": 0,
  "currency": "INR",
  "notes": [],
  "initiator_id": "CJoeHMNpi0nC7k",
  "customer_refund_id": null,
  "created_at": 1580456007
}

Path Parameters🔗

id mandatory: string Unique identifier of the transfer that must be reversed.

Request Parameters🔗

amount optional: integer The amount that is to be reversed from the linked account to your account. If this parameter is not passed, the entire transfer amount will be reversed.

Response Parameters🔗

id: string Unique identifier of the reversal.
entity: string The name of the entity. Here, it is reversal.
transfer_id: string Unique identifier of the transfer that was reversed.
amount: integer The amount that was reversed, in paise.
currency: string ISO currency code. We support route reversals only in INR.
created_at: integer Timestamp in Unix. This indicates when the reversal was created.

Linked Account Settlements🔗

You have complete control over settlements to linked accounts. 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 payment to an account, you can choose to 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. When you put a transfer settlement on hold, the settlement will not happen until you release it.

You can use the following endpoint to create a transfer with settlement configurations:

/payments/:id/transfers

 Curl PHP Node.JS Python Go Response
Copycurl -X POST https://api.razorpay.com/v1/payments/pay_IRPVLKW4sQ5BMX/transfers \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \ 
-H 'content-type: application/json' \
-d '{
  "transfers": [
    {
      "amount": 100,
      "account": "acc_CMaomTz4o0FOFz",
      "currency": "INR",
      "on_hold": 1
    }
  ]
}'

Copy$api = new Api($key_id, $secret);

$api->payment->fetch($paymentId)->transfer(array('account' => $accountId, 'amount' => 500, 'currency' => 'INR','on_hold'=>'1'));

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.payments.transfer(paymentId,{
  "amount": 500,
  "currency": "INR",
  "on_hold": "1"
})

Copyclient = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.payment.transfer(paymentId, {"amount": 500, "currency": "INR",
                        "on_hold": "1"})

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

data:= map[string]interface{}{
  "transfers": []interface{}{
    map[string]interface{}{
      "account": "acc_IRQWUleX4BqvYn",
      "amount": 100,
      "currency": "INR",
      "on_hold": true,
    },
  },
}
body, err := client.Payment.Transfer("<paymentId>", data, nil)

Copy{
  "entity": "collection",
  "count": 1,
  "items": [
    {
      "id": "trf_JJFXnxnvFUhQAy",
      "entity": "transfer",
      "status": "pending",
      "source": "pay_IRPVLKW4sQ5BMX",
      "recipient": "acc_IRQWUleX4BqvYn",
      "amount": 100,
      "currency": "INR",
      "amount_reversed": 0,
      "notes": [],
      "linked_account_notes": [],
      "on_hold": true,
      "on_hold_until": null,
      "recipient_settlement_id": null,
      "created_at": 1649942250,
      "processed_at": null,
      "error": {
        "code": null,
        "description": null,
        "reason": null,
        "field": null,
        "step": null,
        "id": "trf_JJFXnxnvFUhQAy",
        "source": null,
        "metadata": null
      }
    }
  ]
}

Path Parameter🔗

id mandatory: string Unique identifier of the payment on which transfers are to be created.

Request Parameters🔗

transfers

array Enter the details of the transfer.

account mandatory

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

amount mandatory

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 mandatory

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

on_hold mandatory

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

1- Puts the transfer settlement on hold.
0 - Releases the settlement.
For example, if the settlement schedule is T+10 days, a transfer made with on_hold set to 1 will not be settled even after 10 days, as it is on hold. If you release the hold on the T+15 day, the amount will be settled to the linked account by the next working day.

on_hold_until optional

integer Timestamp, in Unix, that indicates until when the settlement of the transfer must be put on hold. If you do not pass the value, the settlement is put on hold indefinitely. For example, if you create a transfer with on_hold_until timestamp defined as 1583991784, the settlement will be held off until the specified time. The amount will be settled to the linked account only on the next day.

notes optional

Settlement Schedule Override:
The settlement schedule defined for the linked account takes precedence over the on_hold and on_hold_until functionality. This simply means that a defined settlement schedule is the minimum time required for the transfer to be settled.
Examples: 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), then the on_hold will change to false on T+7 day, but the settlement will only go out on T+10 day.

Modify Settlement Hold for Transfers🔗

You can use the following endpoint to modify the settlement configuration for a particular transfer_id. On a successful request, the API responds with the modified transfer entity.

/transfers/:id

Watch Out!
You cannot change this setting after the transfer is settled to the linked account.

 Curl PHP Node.JS Python Go Response
Copycurl -X PATCH https://api.razorpay.com/v1/transfers/trf_JJD536GI6wuz3m \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-H 'content-type: application/json' \
-d '{
  "on_hold": 1,
  "on_hold_until": 1679691505
}'

Copy$api = new Api($key_id, $secret);

$api->transfer->fetch($paymentId)->edit(array('on_hold' => '1', 'on_hold_until' => '1679691505'));

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.transfers.edit(paymentId,{
  "on_hold": "1",
  "on_hold_until": "1679691505"
})

Copyclient = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.transfer.edit(paymentId, {"on_hold": 1,
                     "on_hold_until": 1679691505})

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

data:= map[string]interface{}{
  "on_hold": 1,
  "on_hold_until": 1649971331,
}
body, err := client.Transfer.Edit("<transferId>", data, nil)

Copy{
  "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": true,
  "on_hold_until": 1649971331,
  "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_JJD536GI6wuz3m",
    "source": null,
    "metadata": null
  }
}

Path Parameter🔗

id mandatory: string Unique identifier of the transfer for which settlement configurations should be modified.

Request Parameters🔗

on_hold mandatory

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

1 - Put the transfer settlement on hold.
0 - Releases the settlement.
For example, if the settlement schedule is T+10 days, a transfer made with on_hold set to 1 will not be settled even after 10 days, as it is on hold. If the hold is disabled on T+15 day, the amount will be settled to the linked account by the next working day.

on_hold_until optional

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. For example, if a transfer is created with on_hold_until timestamp defined as 1583991784, the settlement will be held off until the specified time period. The amount will be settled to the linked account only on the next day.