Payout Links

Create and fetch Payout Links using APIs.


Watch Out!
Currently, the Payout Link APIs are not available in test mode.

Payout Links enable you to make payouts to those contacts whose fund accounts details are not readily available with you. You can use these links to collect the customer's fund account details and then process refunds, reimbursement and cashbacks to them without additional follow up.

Watch the below video to know how to create Payouts using our APIs.

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

Run in Postman

Create a Payout Link🔗

Use the below endpoint to create a payout link.

/payout-links

Request Parameters🔗

account_numbermandatory

string The account from which you want to make the payout.
Account details can be found on the RazorpayX Dashboard. For example, 7878780080316316.

  • Pass your virtual account number if you want money to be deducted from your virtual account.
  • Pass your current account number if you want money to be deducted from your current account.
    Watch Out!
    This is not your contact's bank account number.
contact

Details of the contact to whom the payout link is to be sent.

idmandatory if no other parameter in the array is used
string

If you are using this, do not use the other parameters in the array.

The unique identifer for the contact. For example, cont_00000000000001.
namemandatory if id is not used
string

Use this only if you are not using the id parameter.

The contact's name. This field is case-sensitive. A minimum of 3 characters and a maximum of 50 characters are allowed. Name cannot end with a special character, except .. Supported characters: a-z, A-Z, 0-9, space, , - , _ , / , ( , ) and , .. For example, Gaurav Kumar.For example, Gaurav Kumar.
contacteither contact or email mandatory if id is not used
string

Use this only if you are not using the id parameter.

The contact's phone number. For example, 9123456789.
emaileither contact or email mandatory if id is not used
string

Use this only if you are not using the id parameter.

The contact's email address. For example, gaurav.kumar@example.com.
typeoptional
string

Use this only if you are not using the id parameter.

Classification for the contact being created. For example, employee.

The following classifications are available by default:
  • vendor
  • customer
  • employee
  • self

    Handy Tips
    Additional classifications can be created via the Dashboard and then used in APIs. It is not possible to create new classifications via the API.
amountmandatory

integer The amount, in paise, to be transferred from the business account to the contact's fund account. For example, if you want to transfer ₹10000, pass 1000000 against this parameter. The minimum value that can be passed is 100. Handy Tips
The value passed here does not include fees and tax. Fees and tax, if any, are deducted from your account balance.

currencymandatory

string The currency in which the payout is being made. Here, it is INR.

purposemandatory

string The purpose of the payout that is being created. For example, refund.

Classifications available by default:

  • refund
  • cashback
  • payout
  • salary
  • utility bill
  • vendor bill

    Handy Tips
    Additional purposes for payouts can be created via the Dashboard and then used in the API. However, it is not possible to create new purpose for the payout via the API.
descriptionmandatory

string Add a description to communicate the context of the payout link to the recipient. For Example, Cashback for Mr. Gaurav Kumar on the purchase on Earl Grey Tea.

receiptoptional

string A user-entered receipt number for the payout. For example, Receipt No. 1.

send_sms

boolean Possible values:

  • true - Razorpay sends the payout link to the provided contact number via SMS.
  • false (default) - You send the payout link to the contact.
send_email

boolean Possible values:

  • true - Razorpay sends the payout link to the provided email address via email.
  • false (default) - You send the payout link to the contact.
notesoptional

object User-entered notes for internal reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example, "note_key": "Beam me up Scotty”.

expire_byoptional

integer Timestamp, in Unix, when you want the payout link to expire. Expire By time must be in seconds and at least 15 minutes ahead of the current time. This field is required only when you want to set an expiry date and time for the payout link.

Handy Tips
Expiry feature for Payout Links must be enabled before sending this parameter. Know more about how to enable the expiry feature.

Response Parameters🔗

id

string The unique identifier of the payout link that is created. For example, poutlk_00000000000001.

entity

string The entity being created. Here it will be payout_link.

contact_id

string The unique identifier of the contact to whom the payout link is to be sent. For example, cont_00000000000001.

contact

Details of the contact to whom the payout link is to be sent.

Use this only if you are not using the contact_id parameter.

name
string The contact's name. For example, Gaurav Kumar.
type
string Classification for the contact being created. For example, employee.
contact
string The contact's phone number. For example, 9123456789.
email
string The contact's email address. For example, gaurav.kumar@example.com.
fund_account_id

string The unique identifier of the contact's fund account to which the payout will be made. This field is populated only when the payout link moves to the processing state. For example, fa_00000000000001.

payout_id

string The unique identifier for the payout made to the contact. This field is populated only when the payout link moves to the processed state. For example, pout_00000000000001.

purpose

string The purpose of the payout. For example, refund.

status

string The payout link status. Possible values:

amount

integer The amount, in paise, to be transferred from the business account to the contact's fund account. Handy Tips
The value passed here does not include fees and tax. Fees and tax, if any, are deducted from your account balance.

currency

string The currency in which the payout is being made. Here, it is INR.

description

string A user-entered description for the payout link. For example, Payout link for Gaurav Kumar.

attempt_count

integer The number of attempts to complete the payout.

receipt

string A user-entered receipt number for the payout. For example, Receipt No. 1.

notes

object User-entered notes for internal reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example, "note_key": "Beam me up Scotty”.

short_url

string A short link for the payout link that was created. This is the link that is shared with the contact.

send_sms

boolean Possible values:

  • true - SMS sent to the provided contact number.
  • false - SMS could not be sent to the provided contact number. This could be because the contact number provided was wrong.
send_email

boolean Possible values:

  • true - Email sent to the provided email address.
  • false - Email could not be sent to the provided email address. This could be because the email address provided was wrong.
created_at

integer Timestamp, in Unix, when the payout link was created.

cancelled_at

integer Timestamp, in Unix, when the payout link was cancelled by you. This field is populated only when the payout link moves to the cancelled state.

expire_by

integer Timestamp, in Unix, when the payout link was to expire. This is set at the time of creation of the payout link. This field is populated only if you have enabled expiry feature for Payout Links. Know more about how to enable the expiry feature.

expired_at

integer Timestamp, in Unix, when the payout link expired. This is set at the time of creation of the payout link.

Fetch All Payout Links🔗

Use the below endpoint to fetch all payout links.

/payout-links

Query Parameters🔗

from
integer Timestamp, in Unix, from when payout links are to be fetched.
to
integer Timestamp, in Unix, till when payout links are to be fetched.
count
integer The number of payout links to be fetched. The default value is 10. The maximum value is 100. This can be used for pagination, in combination with skip.
skip
integer The numbers of payout links to be skipped. The default value is 0. This can be used for pagination, in combination with count.
id
string The unique identifier for the payout link. For example, poutlk_00000000000001.
contact_id
string The unique identifier of the contact to whom the payout link is to be sent. For example, cont_00000000000001.
contact_phone_number
string The contact's phone number. For example, 9123456789.
contact_email
string The contact's email address. For example, gaurav.kumar@example.com.
fund_account_id
string The unique identifier of the contact's fund account to which the payout was made. For example, fa_00000000000001.
purpose
string The purpose of the payout that is being created. For example, refund.
status
string. The payout link status. Possible values:
  • issued
  • processing
  • processed
  • cancelled
receipt
string A user-entered receipt number for the payout. For example, Receipt No. 1.
short_url
string A short link for the payout link that was created. This is the link that is shared with the contact.

Fetch Payout Link by🔗

Handy Tips
To fetch payout details via a payout link, use the endpoint GET with https://api.razorpay.com/v1/payout-links/<add the payout id>?expand[]=payouts.

Use the below endpoint to fetch details of a payout link.

/payout-links/:id

Path Parameter🔗

id mandatory
string The unique identifier for the payout link. For example, poutlk_00000000000001.

Cancel a Payout Link🔗

You can only cancel payout links in the issued state.

Use the below endpoint to cancel a payout link.

/payout-links/:id/cancel

Path Parameter🔗

id mandatory
string The unique identifier for the payout link. For example, poutlk_00000000000003.

Webhooks🔗

Available Events🔗

payout_link.pending
Triggered whenever a payout link moves to the pending state. This indicates that the payout link has been created. Applicable only for cases where approval workflow is set.
payout_link.issued
Triggered whenever a payout link moves to the issued state. This indicates that the payout link has been created.
payout_link.processing
Triggered whenever a payout link moves to the processing state. This indicates that your contact has entered their fund account details and the payout is being processed.
payout_link.processed
Triggered whenever a payout link moves to the processed state. This indicates that the payout has been successfully made.
payout_link.attempted
Triggered whenever the underlying payout has reversed and another attempt is required on the payout link.
payout_link.cancelled
Triggered whenever a payout link moves to the cancelled state. This indicates that you have cancelled the payout link.
payout_link.rejected
Triggered whenever a payout link moves to the rejected state. This indicates that the Approver has rejected the payout link. Applicable only for cases where approval workflow is set.
payout_link.expired
Triggered whenever a payout link moves to the expired state. This indicates that the payout link has expired.

Handy Tips
Expiry feature for Payout Links must be enabled before using this webhook event. Know more about how to enable the expiry feature.

Sample Payloads🔗

payout_link.pending🔗

Triggered whenever a payout link moves to the pending state. This indicates that the payout link has been created. Applicable only for cases where approval workflow is set.

payout_link.issued🔗

Triggered whenever a payout link moves to the issued state. This indicates that the payout link has been created.

payout_link.processing🔗

Triggered whenever a payout link moves to the processing state. This indicates that your contact has entered their fund account details and the payout is being processed.

The fund_account_id is populated at this stage.

payout_link.processed🔗

Triggered whenever a payout link moves to the processed state. This indicates that the payout has been successfully made.

payout_link.attempted🔗

Triggered whenever the underlying payout has reversed and another attempt is required on the payout link.

payout_link.cancelled🔗

Triggered whenever a payout link moves to the cancelled state. This indicates that you have cancelled the payout link.

payout_link.expired🔗

Triggered whenever a payout link moves to the expired state. This indicates that the payout link has expired.

payout_link.rejected🔗

Triggered whenever a payout link moves to the rejected state. This indicates that the payout link has been rejected by the Approver.

×