API ReferenceIntegrationsKnowledge Base

Payout Link APIs

Not available in test mode:
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.

Create a Payout Link#

Use the below endpoint to create a payout link.

/payout-links

Request Parameters#

account_numbermandatory

Data type string. This is the business account from which the payout is to be made. For example, 7878780080316316.
Note:
This is NOT your contact's bank account number.
Business account details can be found on the RazorpayX Dashboard.

contact

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

idmandatory if no other parameter in the array is used
Data type 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
Data type string.

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

The contact's name. For example, Gaurav Kumar.
contacteither contact or email mandatory if id is not used
Data type 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
Data type string.

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

The contact's email address. For example, gaurav.kumar@example.com.
typeoptional
Data type 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

    Additional classifications:
    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

Data type 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. Note:
The value passed here does not include fees and tax. Fees and tax, if any, are deducted from your account balance.

currencymandatory

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

purposemandatory

Data type 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

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

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

receiptoptional

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

send_sms

Data type 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

Data type 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

Data type 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”.

Response Parameters#

id

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

entity

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

contact_id

Data type 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
Data type string. The contact's name. For example, Gaurav Kumar.
type
Data type string. Classification for the contact being created. For example, employee.
contact
Data type string. The contact's phone number. For example, 9123456789.
email
Data type string. The contact's email address. For example, gaurav.kumar@example.com.
fund_account_id

Data type 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

Data type 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

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

status

Data type string. The payout link status. Possible values:

amount

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

currency

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

description

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

receipt

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

notes

Data type 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

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

send_sms

Data type 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

Data type 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

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

cancelled_at

Data type 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.

Fetch All Payout Links#

Use the below endpoint to fetch all payout links.

/payout-links

Query Parameters#

from
Data type integer. Timestamp, in Unix, from when payout links are to be fetched.
to
Data type integer. Timestamp, in Unix, till when payout links are to be fetched.
count
Data type 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
Data type 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
Data type string. The unique identifier for the payout link. For example, poutlk_00000000000001.
contact_id
Data type string. The unique identifier of the contact to whom the payout link is to be sent. For example, cont_00000000000001.
contact_phone_number
Data type string. The contact's phone number. For example, 9123456789.
contact_email
Data type string. The contact's email address. For example, gaurav.kumar@example.com.
fund_account_id
Data type string. The unique identifier of the contact's fund account to which the payout was made. For example, fa_00000000000001.
purpose
Data type string. The purpose of the payout that is being created. For example, refund.
status
Data type string. The payout link status. Possible values:
  • issued
  • processing
  • processed
  • cancelled
receipt
Data type string. A user-entered receipt number for the payout. For example, Receipt No. 1.
short_url
Data type string. A short link for the payout link that was created. This is the link that is shared with the contact.

Fetch a Payout Link#

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

/payout-links/:id

Path Parameter#

id mandatory
Data type 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
Data type string. The unique identifier for the payout link. For example, poutlk_00000000000003.

Webhooks#

Available Events#

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.

Sample Payloads#

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.