{"_id":"58e25b1db5ebbc1b006575d8","initVersion":{"_id":"54dec8b6c2b4b70d009c3f0f","version":"1"},"project":"54c83b5aab706219009e067b","__v":0,"user":{"_id":"584638a6cdb4f10f0014160a","username":"","name":"Jitendra"},"hidden":false,"createdAt":"2017-04-03T14:24:29.224Z","fullscreen":false,"htmlmode":false,"html":"","body":"# On this page\n\n1. [Introduction](#section-introduction)\n   1. [Using our API](#section--using-our-api-)\n   2. [Payment Link Lifecycle](#section--payment-link-lifecycle-)\n2. [Entity structure](#section--entity-structure-)\n3. [APIs](#section--apis-)\n   1. [Creating Payment Link](#section--create-payment-link-)\n   2. [Get Payment Link](#section--get-payment-link-)\n   3. [Fetching (Get) Multiple Payment Link](#section--fetching-get-multiple-payment-link-)\n   4. [Cancel Payment Link](#section--cancel-payment-link-)\n\n# **Introduction**\n\nPayment Links can be used to create links which request the recipient to make a payment for a pre set amount. Once a link is generated and sent the recipient can open it in any browser and make a payment using any method like card, netbanking, UPI or wallet.\n\nPayment Links and its features are a subset of the [Invoices API](https://docs.razorpay.com/v1/page/invoices), and this document only addresses the reduced feature set.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Looking for eCOD?\",\n  \"body\": \"Razorpay also provides an eCOD feature. The details for this are available here: [https://docs.razorpay.com/v1/page/ecod](https://docs.razorpay.com/v1/page/ecod)\"\n}\n[/block]\n## **Using our API**\n\nRefer our [Getting started](https://docs.razorpay.com/docs/getting-started) documentation on API integration to understand the basic concepts of our API usage.\n\n- All the APIs listed below are authenticated via the basic auth.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Auth Required\",\n  \"body\": \"All the APIs require basic authentication.\\n\\n**Private APIs:**\\nThe username is the `key_id` and the password is the `key_secret`.\\nThese APIs should always be called from your server and not from the client. `key_secret` should not be exposed to anyone.\\n\\n **Public APIs:** \\nThe username is the `key_id` and the password is empty. These APIs can be called from client side code as well.\"\n}\n[/block]\n\n- Following is the API response format in case of errors such as form validation error, bad request errors, etc.:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"error\\\": {\\n    \\\"code\\\": \\\"BAD_REQUEST_ERROR\\\",\\n    \\\"description\\\": \\\"amount should always be integer\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Error response example\"\n    }\n  ]\n}\n[/block]\n## **Payment Link Lifecycle**\n\nA payment link at any moment can be in one of the following states:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Status\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"ISSUED\",\n    \"0-1\": \"Payment link has been created and sent to customer.\",\n    \"2-0\": \"PAID\",\n    \"2-1\": \"This status appears when the payment for the link is completed by the customer.\",\n    \"3-0\": \"CANCELLED\",\n    \"3-1\": \"This status appears when the Payment Link has been cancelled.\",\n    \"4-0\": \"EXPIRED\",\n    \"4-1\": \"This status appears when the Payment Link has expired. By default the value is 60 days from time of creation but can be set to any other value at the time of creation. Refer APIs.\",\n    \"1-0\": \"PARTIALLY_PAID\",\n    \"1-1\": \"Payment link has been paid in partial. This is applicable for payment links on which partial payment is enabled at the time of creation. Once all the due amount is paid its moved to paid status.\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n\n# **Entity Structure**\n\nThe following JSON is the representation of the invoice entity for a payment link. It includes almost all of the public attributes of the invoice entity:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\":\\\"inv_7NZ3uS82Rr6elQ\\\",\\n    \\\"entity\\\":\\\"invoice\\\",\\n    \\\"receipt\\\":\\\"max-14-char-no\\\",\\n    \\\"customer_id\\\":\\\"cust_7NZ3uTXhicUQgQ\\\",\\n    \\\"customer\\\":{\\n        \\\"name\\\":null,\\n        \\\"email\\\":\\\"test@test.com\\\",\\n        \\\"contact\\\":\\\"9999999999\\\",\\n        \\\"billing_address\\\":{\\n            \\\"id\\\":\\\"addr_7NZ3uUd4tI7RCF\\\",\\n            \\\"type\\\":\\\"billing_address\\\",\\n            \\\"primary\\\":true,\\n            \\\"line1\\\":\\\"#11, Navi Camp\\\",\\n            \\\"line2\\\":null,\\n            \\\"zipcode\\\":\\\"560076\\\",\\n            \\\"city\\\":\\\"Pandora\\\",\\n            \\\"state\\\":\\\"Karnataka\\\",\\n            \\\"country\\\":\\\"in\\\"\\n        }\\n    },\\n    \\\"order_id\\\":\\\"order_7NZ3uYBFz5sujN\\\",\\n    \\\"payment_id\\\":null,\\n    \\\"status\\\":\\\"issued\\\",\\n    \\\"expire_by\\\":1498439025,\\n    \\\"issued_at\\\":1488439306,\\n    \\\"paid_at\\\":null,\\n    \\\"expired_at\\\":null,\\n    \\\"sms_status\\\":\\\"pending\\\",\\n    \\\"email_status\\\":\\\"pending\\\",\\n    \\\"date\\\":1488439025,\\n    \\\"partial_payment\\\": false,\\n    \\\"terms\\\":\\\"Terms and condition of the service/invoice\\\",\\n    \\\"amount\\\":55000,\\n    \\\"description\\\":\\\"Payment for your purchange at Abcd Store.\\\",\\n    \\\"notes\\\":{\\n        \\\"random_key\\\":\\\"Random note\\\"\\n    },\\n    \\\"currency\\\":\\\"INR\\\",\\n    \\\"short_url\\\":\\\"http://dwarf.razorpay.dev/013ytd7\\\",\\n    \\\"view_less\\\":true,\\n    \\\"type\\\":\\\"link\\\",\\n    \\\"created_at\\\":1488439306\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Payment Link Entity\"\n    }\n  ]\n}\n[/block]\n# **APIs**\n\n## **Create Payment Link** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"POST\",\n    \"0-1\": \"/invoices\",\n    \"0-2\": \"Use this endpoint to create payment links.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"For Payments Links, you need to pass the following fields mandatorily in the create API:\\n- `type: link`\\n- `view_less: 1`\\n\\nWithout these fields, there's no guarantee of the functionality working as described.\",\n  \"title\": \"Mandatory fields for Payment Links\"\n}\n[/block]\n\n**Request Body Attributes**\n\nThe following are the explanations of the attributes which can be sent in the request body. <i>(Includes only ones which needs explanation.)</i>\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Data type\",\n    \"h-2\": \"Requirement\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"customer_id\",\n    \"0-1\": \"string\",\n    \"0-2\": \"Optional\",\n    \"0-3\": \"If you are using Customers API, you can pass the customer_id in this field. If not, you can pass the **customer** object described below.\",\n    \"1-0\": \"customer[name]\",\n    \"1-1\": \"string\",\n    \"1-2\": \"Mandatory, with customer\",\n    \"2-0\": \"customer[email]\",\n    \"2-1\": \"string\",\n    \"2-2\": \"Mandatory, with customer\",\n    \"3-0\": \"customer[contact]\",\n    \"3-1\": \"string\",\n    \"3-2\": \"Mandatory, with customer\",\n    \"4-0\": \"customer[billing_address][line1]\",\n    \"5-0\": \"customer[billing_address][line2]\",\n    \"6-0\": \"customer[billing_address][city]\",\n    \"7-0\": \"customer[billing_address][zipcode]\",\n    \"8-0\": \"customer[billing_address][state]\",\n    \"9-0\": \"customer[billing_address][country]\",\n    \"4-1\": \"string\",\n    \"5-1\": \"string\",\n    \"6-1\": \"string\",\n    \"7-1\": \"string\",\n    \"8-1\": \"string\",\n    \"9-1\": \"string\",\n    \"4-2\": \"Mandatory, with customer[billing_address]\",\n    \"5-2\": \"Optional\",\n    \"6-2\": \"Mandatory, with customer[billing_address]\",\n    \"7-2\": \"Mandatory, with customer[billing_address]\",\n    \"8-2\": \"Mandatory, with customer[billing_address]\",\n    \"9-2\": \"Mandatory, with customer[billing_address]\",\n    \"13-0\": \"expire_by\",\n    \"13-1\": \"epoch/integer\",\n    \"13-2\": \"Optional\\ndefault = 60 days from created time\",\n    \"14-0\": \"sms_notify\",\n    \"14-1\": \"string\\nin: 0|1\",\n    \"14-2\": \"Optional\\ndefault = 1\",\n    \"15-0\": \"email_notify\",\n    \"15-1\": \"string\\nin: 0|1\",\n    \"15-2\": \"Optional\\ndefault = 1\",\n    \"16-0\": \"date\",\n    \"16-1\": \"epoch/integer\",\n    \"16-2\": \"Optional\\ndefault = null\",\n    \"18-0\": \"terms\",\n    \"18-1\": \"string\",\n    \"18-2\": \"Optional\\ndefault = null\",\n    \"11-0\": \"description\",\n    \"11-1\": \"string\",\n    \"11-2\": \"Mandatory\",\n    \"19-0\": \"notes\",\n    \"19-1\": \"object\",\n    \"19-2\": \"Optional\\ndefault = {}\",\n    \"10-0\": \"currency\",\n    \"10-1\": \"string\",\n    \"10-2\": \"Mandatory\",\n    \"20-0\": \"type\",\n    \"20-1\": \"string\\nin: link|ecod|invoice\",\n    \"20-2\": \"Mandatory\",\n    \"10-3\": \"**Only** INR is supported currently.\",\n    \"20-3\": \"Must send type=link\",\n    \"12-0\": \"amount\",\n    \"12-1\": \"integer\",\n    \"12-2\": \"Mandatory\",\n    \"12-3\": \"amount must be in paisa.\",\n    \"17-0\": \"partial_payment\",\n    \"17-1\": \"string\\nin: 0|1\",\n    \"17-2\": \"Optional\\ndefault = 0\",\n    \"17-3\": \"Enables partial payments on the invoice.\"\n  },\n  \"cols\": 4,\n  \"rows\": 21\n}\n[/block]\n\n**Sample request and response**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"customer\\\": {\\n\\t\\t\\\"email\\\": \\\"test@test.com\\\",\\n\\t\\t\\\"contact\\\": \\\"9999999999\\\"\\n\\t},\\n\\t\\\"type\\\": \\\"link\\\",\\n  \\\"view_less\\\": 1,\\n\\t\\\"amount\\\": 2000,\\n\\t\\\"currency\\\": \\\"INR\\\",\\n\\t\\\"description\\\": \\\"Payment link for this purpose - xyz.\\\",\\n  \\\"expire_by\\\": 1493630556\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Request #1\"\n    },\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"inv_7Nb7Y3TKLknKpR\\\",\\n  \\\"entity\\\": \\\"invoice\\\",\\n  \\\"receipt\\\": null,\\n  \\\"customer_id\\\": \\\"cust_7NZ3uTXhicUQgQ\\\",\\n  \\\"customer\\\": {\\n    \\\"name\\\": null,\\n    \\\"email\\\": \\\"test@test.com\\\",\\n    \\\"contact\\\": \\\"9999999999\\\"\\n  },\\n  \\\"customer_details\\\": {\\n    \\\"customer_name\\\": null,\\n    \\\"customer_email\\\": \\\"test@test.com\\\",\\n    \\\"customer_contact\\\": \\\"9999999999\\\",\\n    \\\"customer_address\\\": null\\n  },\\n  \\\"order_id\\\": \\\"order_7Nb7Y5aWIWW8Ey\\\",\\n  \\\"line_items\\\": [],\\n  \\\"payment_id\\\": null,\\n  \\\"status\\\": \\\"issued\\\",\\n  \\\"expire_by\\\": 1493630556,\\n  \\\"issued_at\\\": 1488446556,\\n  \\\"paid_at\\\": null,\\n  \\\"expired_at\\\": null,\\n  \\\"sms_status\\\": \\\"pending\\\",\\n  \\\"email_status\\\": \\\"pending\\\",\\n  \\\"date\\\": 1488446556,\\n  \\\"amount\\\": 2000,\\n  \\\"description\\\": \\\"Payment link for this purpose - xyz.\\\",\\n  \\\"notes\\\": [],\\n  \\\"comment\\\": null,\\n  \\\"currency\\\": \\\"INR\\\",\\n  \\\"short_url\\\": \\\"http://dwarf.razorpay.dev/8q2betd\\\",\\n  \\\"view_less\\\": true,\\n  \\\"type\\\": \\\"link\\\",\\n  \\\"user_id\\\": null,\\n  \\\"created_at\\\": 1488446556\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response #1\"\n    }\n  ]\n}\n[/block]\nNote:\n\n- Once you have created the payment link, the response from Razorpay's API includes a field called `short_url`. This url can be shared with the customer for making the payment.\n\n## **Get Payment Link**\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"GET\",\n    \"0-1\": \"/invoices/{id}\",\n    \"0-2\": \"Gets payment link with given id.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n**Sample Request and Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"inv_7Nb7Y3TKLknKpR\\\",\\n  \\\"entity\\\": \\\"invoice\\\",\\n  \\\"receipt\\\": null,\\n  \\\"customer_id\\\": \\\"cust_7NZ3uTXhicUQgQ\\\",\\n  \\\"customer\\\": {\\n    \\\"name\\\": null,\\n    \\\"email\\\": \\\"test@test.com\\\",\\n    \\\"contact\\\": \\\"9999999999\\\"\\n  },\\n  \\\"customer_details\\\": {\\n    \\\"customer_name\\\": null,\\n    \\\"customer_email\\\": \\\"test@test.com\\\",\\n    \\\"customer_contact\\\": \\\"9999999999\\\",\\n    \\\"customer_address\\\": null\\n  },\\n  \\\"order_id\\\": \\\"order_7Nb7Y5aWIWW8Ey\\\",\\n  \\\"line_items\\\": [],\\n  \\\"payment_id\\\": null,\\n  \\\"status\\\": \\\"issued\\\",\\n  \\\"expire_by\\\": 1493630556,\\n  \\\"issued_at\\\": 1488446556,\\n  \\\"paid_at\\\": null,\\n  \\\"expired_at\\\": null,\\n  \\\"sms_status\\\": \\\"pending\\\",\\n  \\\"email_status\\\": \\\"pending\\\",\\n  \\\"date\\\": 1488446556,\\n  \\\"amount\\\": 2000,\\n  \\\"description\\\": \\\"Payment link for this purpose - xyz.\\\",\\n  \\\"notes\\\": [],\\n  \\\"comment\\\": null,\\n  \\\"currency\\\": \\\"INR\\\",\\n  \\\"short_url\\\": \\\"http://dwarf.razorpay.dev/8q2betd\\\",\\n  \\\"view_less\\\": true,\\n  \\\"type\\\": \\\"link\\\",\\n  \\\"user_id\\\": null,\\n  \\\"created_at\\\": 1488446556\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n## **Fetching (get) multiple Payment Link **\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"GET\",\n    \"0-1\": \"/invoices\",\n    \"0-2\": \"Fetches multiple payment links.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"entity\\\": \\\"collection\\\",\\n  \\\"count\\\": 2,\\n  \\\"items\\\": [\\n    {\\n      \\\"id\\\": \\\"inv_7NbHv4vLbrvzPs\\\",\\n      \\\"entity\\\": \\\"invoice\\\",\\n      \\\"receipt\\\": \\\"max-14-char-n2\\\",\\n      \\\"customer_id\\\": \\\"cust_7NZ3uTXhicUQgQ\\\",\\n      \\\"customer\\\": {\\n        \\\"name\\\": null,\\n        \\\"email\\\": \\\"test@test.com\\\",\\n        \\\"contact\\\": \\\"9999999999\\\",\\n      },\\n      \\\"customer_details\\\": {\\n        \\\"customer_name\\\": null,\\n        \\\"customer_email\\\": \\\"test@test.com\\\",\\n        \\\"customer_contact\\\": \\\"9999999999\\\",\\n        \\\"customer_address\\\": null\\n      },\\n      \\\"order_id\\\": \\\"order_7NbHv8f5jgYemg\\\",\\n      \\\"line_items\\\": [],\\n      \\\"payment_id\\\": null,\\n      \\\"status\\\": \\\"issued\\\",\\n      \\\"expire_by\\\": 1498439025,\\n      \\\"issued_at\\\": 1488447145,\\n      \\\"paid_at\\\": null,\\n      \\\"expired_at\\\": null,\\n      \\\"sms_status\\\": \\\"sent\\\",\\n      \\\"email_status\\\": \\\"sent\\\",\\n      \\\"date\\\": 1488439025,\\n      \\\"terms\\\": \\\"Terms and condition of the service.\\\",\\n      \\\"amount\\\": 55000,\\n      \\\"description\\\": \\\"Purchage of few books\\\",\\n      \\\"notes\\\": {\\n        \\\"random_key\\\": \\\"Random note\\\"\\n      },\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"short_url\\\": \\\"http://dwarf.razorpay.dev/flui3ex\\\",\\n      \\\"view_less\\\": true,\\n      \\\"type\\\": \\\"invoice\\\",\\n      \\\"user_id\\\": null,\\n      \\\"created_at\\\": 1488447145\\n    },\\n    {\\n      \\\"id\\\": \\\"inv_7Nb8kOvRzHP1jc\\\",\\n      \\\"entity\\\": \\\"invoice\\\",\\n      \\\"receipt\\\": null,\\n      \\\"customer_id\\\": \\\"cust_7NZ3uTXhicUQgQ\\\",\\n      \\\"customer\\\": {\\n        \\\"name\\\": null,\\n        \\\"email\\\": \\\"test@test.com\\\",\\n        \\\"contact\\\": \\\"9999999999\\\"\\n      },\\n      \\\"customer_details\\\": {\\n        \\\"customer_name\\\": null,\\n        \\\"customer_email\\\": \\\"test@test.com\\\",\\n        \\\"customer_contact\\\": \\\"9999999999\\\",\\n        \\\"customer_address\\\": null\\n      },\\n      \\\"order_id\\\": \\\"order_7Nb8kR6Z0bhr1P\\\",\\n      \\\"line_items\\\": [],\\n      \\\"payment_id\\\": null,\\n      \\\"status\\\": \\\"issued\\\",\\n      \\\"expire_by\\\": 1493630624,\\n      \\\"issued_at\\\": 1488446624,\\n      \\\"paid_at\\\": null,\\n      \\\"expired_at\\\": null,\\n      \\\"sms_status\\\": \\\"sent\\\",\\n      \\\"email_status\\\": \\\"sent\\\",\\n      \\\"date\\\": 1488446624,\\n      \\\"terms\\\": null,\\n      \\\"amount\\\": 2000,\\n      \\\"description\\\": \\\"Payment link for this purpose - xyz.\\\",\\n      \\\"notes\\\": [],\\n      \\\"comment\\\": null,\\n      \\\"currency\\\": \\\"INR\\\",\\n      \\\"short_url\\\": \\\"http://dwarf.razorpay.dev/x0jkqbu\\\",\\n      \\\"view_less\\\": true,\\n      \\\"type\\\": \\\"link\\\",\\n      \\\"user_id\\\": null,\\n      \\\"created_at\\\": 1488446624\\n    }\\n  ]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n## **Cancel Payment Link** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"POST\",\n    \"0-1\": \"/invoices/{id}/cancel\",\n    \"0-2\": \"Cancels Payment Link with given id.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n- It can only be called on a payment link that is in 'Issued' state.\n- It's response is the invoice entity, similar to create/update API response with `status` attribute's value as `cancelled`.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Invoice Paid Webhook\",\n  \"body\": \"We have a webhook for invoice paid. You can use this to find out when a payment link gets paid by the customer. This can be enabled on your dashboard under the webhooks section.\\nYou can find the documentation [here](https://docs.razorpay.com/v1/page/webhooks)\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Support\",\n  \"body\": \"In case of any issue with integrating Payment Links, please write to us at integrations@razorpay.com\"\n}\n[/block]","slug":"payment-links","title":"Payment Links"}

Payment Links


# On this page 1. [Introduction](#section-introduction) 1. [Using our API](#section--using-our-api-) 2. [Payment Link Lifecycle](#section--payment-link-lifecycle-) 2. [Entity structure](#section--entity-structure-) 3. [APIs](#section--apis-) 1. [Creating Payment Link](#section--create-payment-link-) 2. [Get Payment Link](#section--get-payment-link-) 3. [Fetching (Get) Multiple Payment Link](#section--fetching-get-multiple-payment-link-) 4. [Cancel Payment Link](#section--cancel-payment-link-) # **Introduction** Payment Links can be used to create links which request the recipient to make a payment for a pre set amount. Once a link is generated and sent the recipient can open it in any browser and make a payment using any method like card, netbanking, UPI or wallet. Payment Links and its features are a subset of the [Invoices API](https://docs.razorpay.com/v1/page/invoices), and this document only addresses the reduced feature set. [block:callout] { "type": "info", "title": "Looking for eCOD?", "body": "Razorpay also provides an eCOD feature. The details for this are available here: [https://docs.razorpay.com/v1/page/ecod](https://docs.razorpay.com/v1/page/ecod)" } [/block] ## **Using our API** Refer our [Getting started](https://docs.razorpay.com/docs/getting-started) documentation on API integration to understand the basic concepts of our API usage. - All the APIs listed below are authenticated via the basic auth. [block:callout] { "type": "info", "title": "Auth Required", "body": "All the APIs require basic authentication.\n\n**Private APIs:**\nThe username is the `key_id` and the password is the `key_secret`.\nThese APIs should always be called from your server and not from the client. `key_secret` should not be exposed to anyone.\n\n **Public APIs:** \nThe username is the `key_id` and the password is empty. These APIs can be called from client side code as well." } [/block] - Following is the API response format in case of errors such as form validation error, bad request errors, etc.: [block:code] { "codes": [ { "code": "{\n \"error\": {\n \"code\": \"BAD_REQUEST_ERROR\",\n \"description\": \"amount should always be integer\"\n }\n}", "language": "json", "name": "Error response example" } ] } [/block] ## **Payment Link Lifecycle** A payment link at any moment can be in one of the following states: [block:parameters] { "data": { "h-0": "Status", "h-1": "Description", "0-0": "ISSUED", "0-1": "Payment link has been created and sent to customer.", "2-0": "PAID", "2-1": "This status appears when the payment for the link is completed by the customer.", "3-0": "CANCELLED", "3-1": "This status appears when the Payment Link has been cancelled.", "4-0": "EXPIRED", "4-1": "This status appears when the Payment Link has expired. By default the value is 60 days from time of creation but can be set to any other value at the time of creation. Refer APIs.", "1-0": "PARTIALLY_PAID", "1-1": "Payment link has been paid in partial. This is applicable for payment links on which partial payment is enabled at the time of creation. Once all the due amount is paid its moved to paid status." }, "cols": 2, "rows": 5 } [/block] # **Entity Structure** The following JSON is the representation of the invoice entity for a payment link. It includes almost all of the public attributes of the invoice entity: [block:code] { "codes": [ { "code": "{\n \"id\":\"inv_7NZ3uS82Rr6elQ\",\n \"entity\":\"invoice\",\n \"receipt\":\"max-14-char-no\",\n \"customer_id\":\"cust_7NZ3uTXhicUQgQ\",\n \"customer\":{\n \"name\":null,\n \"email\":\"test@test.com\",\n \"contact\":\"9999999999\",\n \"billing_address\":{\n \"id\":\"addr_7NZ3uUd4tI7RCF\",\n \"type\":\"billing_address\",\n \"primary\":true,\n \"line1\":\"#11, Navi Camp\",\n \"line2\":null,\n \"zipcode\":\"560076\",\n \"city\":\"Pandora\",\n \"state\":\"Karnataka\",\n \"country\":\"in\"\n }\n },\n \"order_id\":\"order_7NZ3uYBFz5sujN\",\n \"payment_id\":null,\n \"status\":\"issued\",\n \"expire_by\":1498439025,\n \"issued_at\":1488439306,\n \"paid_at\":null,\n \"expired_at\":null,\n \"sms_status\":\"pending\",\n \"email_status\":\"pending\",\n \"date\":1488439025,\n \"partial_payment\": false,\n \"terms\":\"Terms and condition of the service/invoice\",\n \"amount\":55000,\n \"description\":\"Payment for your purchange at Abcd Store.\",\n \"notes\":{\n \"random_key\":\"Random note\"\n },\n \"currency\":\"INR\",\n \"short_url\":\"http://dwarf.razorpay.dev/013ytd7\",\n \"view_less\":true,\n \"type\":\"link\",\n \"created_at\":1488439306\n}", "language": "json", "name": "Payment Link Entity" } ] } [/block] # **APIs** ## **Create Payment Link** [block:parameters] { "data": { "h-0": "Method", "h-1": "Endpoint", "h-2": "Description", "0-0": "POST", "0-1": "/invoices", "0-2": "Use this endpoint to create payment links." }, "cols": 3, "rows": 1 } [/block] [block:callout] { "type": "warning", "body": "For Payments Links, you need to pass the following fields mandatorily in the create API:\n- `type: link`\n- `view_less: 1`\n\nWithout these fields, there's no guarantee of the functionality working as described.", "title": "Mandatory fields for Payment Links" } [/block] **Request Body Attributes** The following are the explanations of the attributes which can be sent in the request body. <i>(Includes only ones which needs explanation.)</i> [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Data type", "h-2": "Requirement", "h-3": "Description", "0-0": "customer_id", "0-1": "string", "0-2": "Optional", "0-3": "If you are using Customers API, you can pass the customer_id in this field. If not, you can pass the **customer** object described below.", "1-0": "customer[name]", "1-1": "string", "1-2": "Mandatory, with customer", "2-0": "customer[email]", "2-1": "string", "2-2": "Mandatory, with customer", "3-0": "customer[contact]", "3-1": "string", "3-2": "Mandatory, with customer", "4-0": "customer[billing_address][line1]", "5-0": "customer[billing_address][line2]", "6-0": "customer[billing_address][city]", "7-0": "customer[billing_address][zipcode]", "8-0": "customer[billing_address][state]", "9-0": "customer[billing_address][country]", "4-1": "string", "5-1": "string", "6-1": "string", "7-1": "string", "8-1": "string", "9-1": "string", "4-2": "Mandatory, with customer[billing_address]", "5-2": "Optional", "6-2": "Mandatory, with customer[billing_address]", "7-2": "Mandatory, with customer[billing_address]", "8-2": "Mandatory, with customer[billing_address]", "9-2": "Mandatory, with customer[billing_address]", "13-0": "expire_by", "13-1": "epoch/integer", "13-2": "Optional\ndefault = 60 days from created time", "14-0": "sms_notify", "14-1": "string\nin: 0|1", "14-2": "Optional\ndefault = 1", "15-0": "email_notify", "15-1": "string\nin: 0|1", "15-2": "Optional\ndefault = 1", "16-0": "date", "16-1": "epoch/integer", "16-2": "Optional\ndefault = null", "18-0": "terms", "18-1": "string", "18-2": "Optional\ndefault = null", "11-0": "description", "11-1": "string", "11-2": "Mandatory", "19-0": "notes", "19-1": "object", "19-2": "Optional\ndefault = {}", "10-0": "currency", "10-1": "string", "10-2": "Mandatory", "20-0": "type", "20-1": "string\nin: link|ecod|invoice", "20-2": "Mandatory", "10-3": "**Only** INR is supported currently.", "20-3": "Must send type=link", "12-0": "amount", "12-1": "integer", "12-2": "Mandatory", "12-3": "amount must be in paisa.", "17-0": "partial_payment", "17-1": "string\nin: 0|1", "17-2": "Optional\ndefault = 0", "17-3": "Enables partial payments on the invoice." }, "cols": 4, "rows": 21 } [/block] **Sample request and response** [block:code] { "codes": [ { "code": "{\n\t\"customer\": {\n\t\t\"email\": \"test@test.com\",\n\t\t\"contact\": \"9999999999\"\n\t},\n\t\"type\": \"link\",\n \"view_less\": 1,\n\t\"amount\": 2000,\n\t\"currency\": \"INR\",\n\t\"description\": \"Payment link for this purpose - xyz.\",\n \"expire_by\": 1493630556\n}", "language": "json", "name": "Request #1" }, { "code": "{\n \"id\": \"inv_7Nb7Y3TKLknKpR\",\n \"entity\": \"invoice\",\n \"receipt\": null,\n \"customer_id\": \"cust_7NZ3uTXhicUQgQ\",\n \"customer\": {\n \"name\": null,\n \"email\": \"test@test.com\",\n \"contact\": \"9999999999\"\n },\n \"customer_details\": {\n \"customer_name\": null,\n \"customer_email\": \"test@test.com\",\n \"customer_contact\": \"9999999999\",\n \"customer_address\": null\n },\n \"order_id\": \"order_7Nb7Y5aWIWW8Ey\",\n \"line_items\": [],\n \"payment_id\": null,\n \"status\": \"issued\",\n \"expire_by\": 1493630556,\n \"issued_at\": 1488446556,\n \"paid_at\": null,\n \"expired_at\": null,\n \"sms_status\": \"pending\",\n \"email_status\": \"pending\",\n \"date\": 1488446556,\n \"amount\": 2000,\n \"description\": \"Payment link for this purpose - xyz.\",\n \"notes\": [],\n \"comment\": null,\n \"currency\": \"INR\",\n \"short_url\": \"http://dwarf.razorpay.dev/8q2betd\",\n \"view_less\": true,\n \"type\": \"link\",\n \"user_id\": null,\n \"created_at\": 1488446556\n}", "language": "json", "name": "Response #1" } ] } [/block] Note: - Once you have created the payment link, the response from Razorpay's API includes a field called `short_url`. This url can be shared with the customer for making the payment. ## **Get Payment Link** [block:parameters] { "data": { "h-0": "Method", "h-1": "Endpoint", "h-2": "Description", "0-0": "GET", "0-1": "/invoices/{id}", "0-2": "Gets payment link with given id." }, "cols": 3, "rows": 1 } [/block] **Sample Request and Response** [block:code] { "codes": [ { "code": "{\n \"id\": \"inv_7Nb7Y3TKLknKpR\",\n \"entity\": \"invoice\",\n \"receipt\": null,\n \"customer_id\": \"cust_7NZ3uTXhicUQgQ\",\n \"customer\": {\n \"name\": null,\n \"email\": \"test@test.com\",\n \"contact\": \"9999999999\"\n },\n \"customer_details\": {\n \"customer_name\": null,\n \"customer_email\": \"test@test.com\",\n \"customer_contact\": \"9999999999\",\n \"customer_address\": null\n },\n \"order_id\": \"order_7Nb7Y5aWIWW8Ey\",\n \"line_items\": [],\n \"payment_id\": null,\n \"status\": \"issued\",\n \"expire_by\": 1493630556,\n \"issued_at\": 1488446556,\n \"paid_at\": null,\n \"expired_at\": null,\n \"sms_status\": \"pending\",\n \"email_status\": \"pending\",\n \"date\": 1488446556,\n \"amount\": 2000,\n \"description\": \"Payment link for this purpose - xyz.\",\n \"notes\": [],\n \"comment\": null,\n \"currency\": \"INR\",\n \"short_url\": \"http://dwarf.razorpay.dev/8q2betd\",\n \"view_less\": true,\n \"type\": \"link\",\n \"user_id\": null,\n \"created_at\": 1488446556\n}", "language": "json", "name": "Response" } ] } [/block] ## **Fetching (get) multiple Payment Link ** [block:parameters] { "data": { "h-0": "Method", "h-1": "Endpoint", "h-2": "Description", "0-0": "GET", "0-1": "/invoices", "0-2": "Fetches multiple payment links." }, "cols": 3, "rows": 1 } [/block] [block:code] { "codes": [ { "code": "{\n \"entity\": \"collection\",\n \"count\": 2,\n \"items\": [\n {\n \"id\": \"inv_7NbHv4vLbrvzPs\",\n \"entity\": \"invoice\",\n \"receipt\": \"max-14-char-n2\",\n \"customer_id\": \"cust_7NZ3uTXhicUQgQ\",\n \"customer\": {\n \"name\": null,\n \"email\": \"test@test.com\",\n \"contact\": \"9999999999\",\n },\n \"customer_details\": {\n \"customer_name\": null,\n \"customer_email\": \"test@test.com\",\n \"customer_contact\": \"9999999999\",\n \"customer_address\": null\n },\n \"order_id\": \"order_7NbHv8f5jgYemg\",\n \"line_items\": [],\n \"payment_id\": null,\n \"status\": \"issued\",\n \"expire_by\": 1498439025,\n \"issued_at\": 1488447145,\n \"paid_at\": null,\n \"expired_at\": null,\n \"sms_status\": \"sent\",\n \"email_status\": \"sent\",\n \"date\": 1488439025,\n \"terms\": \"Terms and condition of the service.\",\n \"amount\": 55000,\n \"description\": \"Purchage of few books\",\n \"notes\": {\n \"random_key\": \"Random note\"\n },\n \"currency\": \"INR\",\n \"short_url\": \"http://dwarf.razorpay.dev/flui3ex\",\n \"view_less\": true,\n \"type\": \"invoice\",\n \"user_id\": null,\n \"created_at\": 1488447145\n },\n {\n \"id\": \"inv_7Nb8kOvRzHP1jc\",\n \"entity\": \"invoice\",\n \"receipt\": null,\n \"customer_id\": \"cust_7NZ3uTXhicUQgQ\",\n \"customer\": {\n \"name\": null,\n \"email\": \"test@test.com\",\n \"contact\": \"9999999999\"\n },\n \"customer_details\": {\n \"customer_name\": null,\n \"customer_email\": \"test@test.com\",\n \"customer_contact\": \"9999999999\",\n \"customer_address\": null\n },\n \"order_id\": \"order_7Nb8kR6Z0bhr1P\",\n \"line_items\": [],\n \"payment_id\": null,\n \"status\": \"issued\",\n \"expire_by\": 1493630624,\n \"issued_at\": 1488446624,\n \"paid_at\": null,\n \"expired_at\": null,\n \"sms_status\": \"sent\",\n \"email_status\": \"sent\",\n \"date\": 1488446624,\n \"terms\": null,\n \"amount\": 2000,\n \"description\": \"Payment link for this purpose - xyz.\",\n \"notes\": [],\n \"comment\": null,\n \"currency\": \"INR\",\n \"short_url\": \"http://dwarf.razorpay.dev/x0jkqbu\",\n \"view_less\": true,\n \"type\": \"link\",\n \"user_id\": null,\n \"created_at\": 1488446624\n }\n ]\n}", "language": "json", "name": "Response" } ] } [/block] ## **Cancel Payment Link** [block:parameters] { "data": { "h-0": "Method", "h-1": "Endpoint", "h-2": "Description", "0-0": "POST", "0-1": "/invoices/{id}/cancel", "0-2": "Cancels Payment Link with given id." }, "cols": 3, "rows": 1 } [/block] - It can only be called on a payment link that is in 'Issued' state. - It's response is the invoice entity, similar to create/update API response with `status` attribute's value as `cancelled`. [block:callout] { "type": "info", "title": "Invoice Paid Webhook", "body": "We have a webhook for invoice paid. You can use this to find out when a payment link gets paid by the customer. This can be enabled on your dashboard under the webhooks section.\nYou can find the documentation [here](https://docs.razorpay.com/v1/page/webhooks)" } [/block] [block:callout] { "type": "info", "title": "Support", "body": "In case of any issue with integrating Payment Links, please write to us at integrations@razorpay.com" } [/block]