API ReferenceIntegrationsKnowledge Base

Payment Links

New API Version:
We are introducing a new version of APIs for Payment Links. This will be available from 01 Sep 2020.


Old API URL: https://api.razorpay.com/v1/invoices


New API URL: https://api.razorpay.com/v1/payment_links

Some of the existing request and response parameters have changed and new ones have been added.

Pass this information to your developers and ask them to change your integration accordingly.



Payment Links are URLs that you can send to your customers through SMS and email to collect payments from them. Customers can click on the URL, which opens the payment request page, and complete the payment using any of the available payment methods.

You can easily set up and use Payment Links with these APIs:

Postman Collection#

We have a Postman collection to make the integration quicker and easier. Click the Download Postman Collection button below to get started.

Instructions for using the Postman Collection#

  • All Razorpay APIs are authorized using Basic Authorization.
    • Generate API Keys from the Dashboard .
    • Add your API Keys in Postman. Selected the required API → Auth → Type = Basic Auth → Username = <Your_Key_ID>; Password = <Your_Key_secret>
  • Some APIs in the collection require data specific to your account either in the request body or as path or query parameters.
    • For example, the Fetch a Payment Link API requires you to add the inv_id as a path parameter in the endpoint.
    • Such parameters are enclosed with {} in the collection. For example, {inv_id}.
    • The API throws an error if these values are incorrect or do not exist in your system.The API throws an error if this value is incorrect or does not exist in your system.

Payment Link Entity#

The following table details some of the attributes related to Payment Links:

id

string The unique identifier of the Payment Link generated.

receipt

string The unique number added for each Payment Link by you for internal reference. The maximum character limit supported is 40.

customer_id

string Unique identifier of the customer to whom the Payment Link has been sent.

customer

Customer details

name
string The customer's name. The maximum character limit supported is 50.
contact
string The customer's mobile number.
email
string The customer's email address.
status

string Indicates the current status of the Payment Link. Refer to the Payment Links Life Cycle to learn about the different statuses.

expire_by

integer Timestamp, in Unix, when the Payment Link will expire.

issued_at

integer Timestamp, in Unix, at which the Payment Link was issued to the customer.

paid_at

integer Timestamp, in Unix, at which the payment was made. Here, the value will be null as the link has just been created.

cancelled_at

integer Timestamp, in Unix, at which the Payment Link was cancelled by you. Here, the value will be null.

expired_at

integer Timestamp, in Unix, at which the Payment Link expired.

sms_status

string Indicates whether the SMS notification for the Payment Link was sent to the customer. Possible values:

  • pending
  • sent
email_status

string Indicates whether the email notification for the Payment Link was sent to the customer. Possible values:

  • pending
  • sent
partial_payment

boolean Possible values:

  • true - Customer can make partial payments.
  • false (default) - Customer cannot make partial payments.
amount

integer Amount to be paid using the Payment Link. Must be in the smallest unit of the currency. For example, if you want to receive a payment of ₹299.95, you must enter the value 29995.

amount_paid

integer Amount paid using the Payment Link.

amount_due

integer Remaining amount to be paid using the Payment Link.

currency

string Currency in which the payment was made. Defaults to INR. We accept payments in international currencies.

description

string A brief description of the Payment Link. The maximum character limit supported is 2048.

notes

object User-entered notes for internal reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. Any custom notes added to the link.

short_url

string The short URL that is generated. This is the Payment Link that can be shared with customers to accept payments. Once cancelled, no payments can be accepted using the link.

view_less

boolean Used when the Payment Link's description is lengthy and you want to make the text collapsible. The text can be expanded by the customer using the Show More link.

  • true (default) - Payment Link's description appears collapsed, with a Show More link.
  • false - Payment Link's description appears expanded.
type

string Here it will be link.

Create Payment Link#

You have the option to create basic or customized Payment Links:

Customized Payment Links
You can customize Payment Links as per your business requirements.

Basic Payment Links
These are normal, non-customized Payment Links, which are not customized as per your business preferences.

Use the below endpoint to create a basic Payment Link.

/invoices

Request Parameters#

Following table lists the attributes and their explanations, which are sent in the request body:

type mandatory

string Here it will be link.

amount mandatory

integer Amount must be in the smallest unit of the currency. For example, pass 1000 for ₹10.

description mandatory

string A brief description of the Payment Link. For example, Payment Link for Birthday gift. The maximum character limit supported is 2048.

customer_id optional

string You can pass the cust_id in this field, if you are using Customers API. If not, you can pass the customer object described in the below fields.

customer

Customer details.

name optional
string The customer's name. For example, Gaurav Kumar. The maximum character limit supported is 50.
email optional
string The customer's email address. For example, gaurav.kumar@example.com.
contact optional
string The customer's mobile number. For example, 9876543210.
view_less optional

boolean Used when the Payment Link's description is lengthy and you want to make the text collapsible. The text can be expanded by the customer using the Show More link.

  • 0 - Payment Link's description appears expanded.
  • 1 (default) - Payment Link's description appears collapsed, with a Show More link.
currency optional

string Defaults to INR. We accept payments in international currencies.

receipt optional

string Receipt number tagged to the Payment Link. Must be a unique value for each Payment Link. The maximum character limit supported is 40.

reminder_enable optional

boolean Used to send reminders for the Payment Link. Possible values:

  • true - To send reminders.
  • false - To disable reminders.
expire_by optional

integer Timestamp, in Unix, when the payment link will expire.

sms_notify optional

boolean Defines who handles the SMS notification to the customer. Possible values:

  • 0 - You send the SMS.
  • 1 (default) - Razorpay sends the SMS.
email_notify optional

boolean Defines who handles the Email notification to the customer. Possible values:

  • 0 - You send the email.
  • 1 (default) - Razorpay sends the email.
notes optional

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”. Refer to Notes section of the API Reference Guide to learn more.

partial_payment optional

boolean Possible values:

  • true - Customer can make partial payments.
  • false (default) - Customer cannot make partial payments.
callback_url optional

string If specified, adds a redirect URL to the Payment Link. Once the customer completes the payment, he is redirected to the specified URL.

callback_method conditionally mandatory

string If callback_url parameter is passed, callback_method must be passed with the value get.

Using callback_url Parameter#

After successful completion of the payment, customers can be redirected to a specific URL using the callback_url and callback_method parameters.

For example, you can redirect customers to https://example-callback-url.com/.

razorpay_payment_id
Payment ID of the successful payment.
razorpay_invoice_id
Invoice ID generated at the time of link or invoice creation.
razorpay_invoice_receipt
Internal order ID set by you for business reference using the receipt parameter at the time of link or invoice creation. No value is returned if 'receipt' parameter was not used.
razorpay_invoice_status
Current status of the link or invoice.
razorpay_signature
Signature for server-side validation to be calculated as HMAC hex digest using SHA256 algorithm. This is described below with a sample code.

The query parameters appear appended to the URL as shown:

Copyhttps://example-callback-url.com/?razorpay_payment_id=pay_DaCTRWQeB2X5bI
&razorpay_invoice_id=inv_DaCT0gxLjIOMIO
&razorpay_invoice_status=paid
&razorpay_invoice_receipt=TS1988
&razorpay_signature=43e11766cb58d6a15cbcbe255dff93da57d3cfcf44d157921143fd7ace3b7196

Verify Signature#

You can verify the razorpay_signature parameter to validate that it is authentic and sent from Razorpay servers.

The razorpay_invoice_id​ attribute should have been stored in your system against an order, right after it was returned in the response to the create Payment Link/ Invoices API request. This is displayed as just id (for example, "id": "inv_DaCT0gxLjIOMIO") in the response.

The razorpay_signature should be validated by your server. In order to verify the signature, you need to create a signature using razorpay_invoice_id, razorpay_invoice_receipt, razorpay_invoice_status and razorpay_payment_id​ as payload and your key_secret​ (your API secret) as secret.

After validating the signature, you should fetch the order in your system corresponding to the razorpay_invoice_id​ and mark this order successful.

Response Parameters#

id

string The unique identifier of the Payment Link generated.

receipt

string The unique number added for each Payment Link by you for internal reference. The maximum character limit supported is 40.

customer_id

string Unique identifier of the customer to whom the Payment Link has been sent.

customer

Customer details

name
string The customer's name. The maximum character limit supported is 50.
contact
string The customer's mobile number.
email
string The customer's email address.
status

string Indicates the current status of the Payment Link. Refer to the Payment Links Life Cycle to learn about the different statuses.

expire_by

integer Timestamp, in Unix, when the Payment Link will expire.

issued_at

integer Timestamp, in Unix, at which the Payment Link was issued to the customer.

paid_at

integer Timestamp, in Unix, at which the payment was made. Here, the value will be null as the link has just been created.

cancelled_at

integer Timestamp, in Unix, at which the Payment Link was cancelled by you. Here, the value will be null.

expired_at

integer Timestamp, in Unix, at which the Payment Link expired.

sms_status

string Indicates whether the SMS notification for the Payment Link was sent to the customer. Possible values:

  • pending
  • sent
email_status

string Indicates whether the email notification for the Payment Link was sent to the customer. Possible values:

  • pending
  • sent
partial_payment

boolean Possible values:

  • true - Customer can make partial payments.
  • false (default) - Customer cannot make partial payments.
amount

integer Amount to be paid using the Payment Link. Must be in the smallest unit of the currency. For example, if you want to receive a payment of ₹299.95, you must enter the value 29995.

amount_paid

integer Amount paid using the Payment Link.

amount_due

integer Remaining amount to be paid using the Payment Link.

currency

string Currency in which the payment was made. Defaults to INR. We accept payments in international currencies.

description

string A brief description of the Payment Link. The maximum character limit supported is 2048.

notes

object User-entered notes for internal reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. Any custom notes added to the link.

short_url

string The short URL that is generated. This is the Payment Link that can be shared with customers to accept payments. Once cancelled, no payments can be accepted using the link.

view_less

boolean Used when the Payment Link's description is lengthy and you want to make the text collapsible. The text can be expanded by the customer using the Show More link.

  • true (default) - Payment Link's description appears collapsed, with a Show More link.
  • false - Payment Link's description appears expanded.
type

string Here it will be link.

Once you have created the Payment Link, the response from Razorpay API includes a field called short_url. This URL can be shared with the customer by any other means as well, for making the payment.

Fetch Payment Link#

You can fetch:

All Payment Links#

Use the following endpoint to fetch all payment links:

/invoices/?type=link

Query Parameters#

payment_id
Unique identifier of the payment associated with the Payment Link.
receipt
The unique receipt number entered while creating the Payment Link.
customer_id
The unique identifier of the customer.

Specific Payment Links by ID#

Use the below endpoint to fetch details of a particular Payment Link.

/invoices/:id

Path Parameter#

id mandatory
string Unique identifier of the Payment Link.

Send or Resend Notifications#

You can send or resend notifications to customer via email and SMS, using following endpoint:

/invoices/:id/notify_by/:medium

Path Parameters#

id mandatory
string Unique identifier of the Payment Link that should be resent.
medium mandatory
string Medium through which the Payment Link must be resent. Allowed values are:
-sms
- email.

Update Payment Link#

Use the below endpoint to update the Payment Link:

/invoices/:id

Path Parameter#

id mandatory
string The unique identifier of the Payment Link that needs to be updated.

Request Parameters#

partial_payment optional
boolean Set this to true to receive partial payments on the link.
receipt optional
string Add a unique receipt number to an existing link.
expire_by optional
integer Specify a Unix timestamp for the expiry of the link.

Cancel Payment Link#

You can cancel a Payment Link with given ID using the following endpoint:

/invoices/:id/cancel

Path Parameter#

id mandatory
string Unique identifier of the Payment Link.

Response Parameters#

id

string The unique identifier of the Payment Link generated.

receipt

string The unique number added for each Payment Link by you for internal reference. The maximum character limit supported is 40.

customer_id

string Unique identifier of the customer to whom the Payment Link has been sent.

customer

Customer details

name
string The customer's name. The maximum character limit supported is 50.
contact
string The customer's mobile number.
email
string The customer's email address.
status

string Indicates the current status of the Payment Link. Refer to the Payment Links Life Cycle to learn about the different statuses.

expire_by

integer Timestamp, in Unix, when the Payment Link will expire.

issued_at

integer Timestamp, in Unix, at which the Payment Link was issued to the customer.

paid_at

integer Timestamp, in Unix, at which the payment was made. Here, the value will be null as the link has just been created.

cancelled_at

integer Timestamp, in Unix, at which the Payment Link was cancelled by you. Here, the value will be null.

expired_at

integer Timestamp, in Unix, at which the Payment Link expired.

sms_status

string Indicates whether the SMS notification for the Payment Link was sent to the customer. Possible values:

  • pending
  • sent
email_status

string Indicates whether the email notification for the Payment Link was sent to the customer. Possible values:

  • pending
  • sent
partial_payment

boolean Possible values:

  • true - Customer can make partial payments.
  • false (default) - Customer cannot make partial payments.
amount

integer Amount to be paid using the Payment Link. Must be in the smallest unit of the currency. For example, if you want to receive a payment of ₹299.95, you must enter the value 29995.

amount_paid

integer Amount paid using the Payment Link.

amount_due

integer Remaining amount to be paid using the Payment Link.

currency

string Currency in which the payment was made. Defaults to INR. We accept payments in international currencies.

description

string A brief description of the Payment Link. The maximum character limit supported is 2048.

notes

object User-entered notes for internal reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. Any custom notes added to the link.

short_url

string The short URL that is generated. This is the Payment Link that can be shared with customers to accept payments. Once cancelled, no payments can be accepted using the link.

view_less

boolean Used when the Payment Link's description is lengthy and you want to make the text collapsible. The text can be expanded by the customer using the Show More link.

  • true (default) - Payment Link's description appears collapsed, with a Show More link.
  • false - Payment Link's description appears expanded.
type

string Here it will be link.

Note:
You can cancel a Payment Link only if it is in issued state.


‹›
×