POSTCreate Link API
Use Case
- This API will be used to create new payment links
- It can be used to create all 3 types of links
- The merchant also has an option to send the link to a customer via SMS/Email
- The merchant can attach a form template to the link using this API
Request Attributes
Head
Attribute | Description |
---|---|
timestamp string(15) optional | EPOCH timestamp of the time at which request is being sent. |
tokenType string mandatory | This parameter identifies whether the API works on checksum authentication. The value to be sent in tokenType is 'AES' for this API. |
signature string(108) mandatory | Paytm validates the request and ensures that parameters are not tempered by verifying the signature in the request. For creating the checksum (signature) refer to the steps given in Checksum Logic. |
Body
Attribute | Description | ||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
merchantRequestId string(64) optional | Unique ID to be generated by merchant. | ||||||||||||||||||||||||||||||||||||||||||||||||
mid string(20) mandatory | Paytm provides MID as a unique identifier to each merchant. For your staging MID, click here. You get the production MID post the account activation. Example: INTEGR7769XXXXXX9383 | ||||||||||||||||||||||||||||||||||||||||||||||||
linkName string(64) mandatory | Name of the link that merchant want to display to customer, linkName is used to generate long url. | ||||||||||||||||||||||||||||||||||||||||||||||||
linkDescription string(30) mandatory | Description of the link that merchant wants to display to customer. | ||||||||||||||||||||||||||||||||||||||||||||||||
linkType string mandatory | Type of link Example: FIXED, GENERIC, INVOICE | ||||||||||||||||||||||||||||||||||||||||||||||||
amount double optional | Transaction amount | ||||||||||||||||||||||||||||||||||||||||||||||||
sendSms boolean optional | Flag whether SMS to be sent to customer by Paytm | ||||||||||||||||||||||||||||||||||||||||||||||||
sendEmail boolean optional | Flag whether Email to be sent to customer by Paytm | ||||||||||||||||||||||||||||||||||||||||||||||||
customerContact object optional | Contact details of customer, refer the Customer Contact | ||||||||||||||||||||||||||||||||||||||||||||||||
CustomerContact +
| |||||||||||||||||||||||||||||||||||||||||||||||||
customerId string(64) optional | Customer id | ||||||||||||||||||||||||||||||||||||||||||||||||
statusCallbackUrl string optional | Callback URL which will be used by Paytm to post the status of the transaction post payment | ||||||||||||||||||||||||||||||||||||||||||||||||
maxPaymentsAllowed string optional | Specify the maximum number of payments you wish to accept via the link | ||||||||||||||||||||||||||||||||||||||||||||||||
templateId string optional | Attach a form specified by the template ID to your link | ||||||||||||||||||||||||||||||||||||||||||||||||
linkNotes string(254) optional | Add additional notes to your link. This won’t be shown to your customers | ||||||||||||||||||||||||||||||||||||||||||||||||
invoiceId string conditional | Invoice number or unique id | ||||||||||||||||||||||||||||||||||||||||||||||||
expiryDate string conditional | Link expiry date | ||||||||||||||||||||||||||||||||||||||||||||||||
invoicePhoneNo string optional | Merchant contact number | ||||||||||||||||||||||||||||||||||||||||||||||||
invoiceEmail string optional | Merchant email address | ||||||||||||||||||||||||||||||||||||||||||||||||
invoiceDetails object optional | Product details with price and tax | ||||||||||||||||||||||||||||||||||||||||||||||||
InvoiceDetails +
| |||||||||||||||||||||||||||||||||||||||||||||||||
partialPayment string mandatory | Flag to let customer make payments in parts Possible Values: true | ||||||||||||||||||||||||||||||||||||||||||||||||
bindLinkIdMobile boolean mandatory | Flag to restrict payment from a particular mobile number | ||||||||||||||||||||||||||||||||||||||||||||||||
resellerId string optional | Applicable for resellers. The ID will be shared at the time of onboarding. Example: "Dipend011" | ||||||||||||||||||||||||||||||||||||||||||||||||
splitSettlementInfo object optional | Split payment details | ||||||||||||||||||||||||||||||||||||||||||||||||
SplitSettlementInfo +
| |||||||||||||||||||||||||||||||||||||||||||||||||
customPaymentSuccessMessage string(254) optional | Successful payment acknowledgement | ||||||||||||||||||||||||||||||||||||||||||||||||
redirectionUrlSuccess string optional | Success redirects the customer to the mentioned URL post successful transaction Example: https://example.test/test | ||||||||||||||||||||||||||||||||||||||||||||||||
redirectionUrlFailure string optional | Failure redirects the customer to the mentioned URL in case the transaction fails Example: https://example.test/test | ||||||||||||||||||||||||||||||||||||||||||||||||
simplifiedSubvention Object optional | Object of Simplified subvention. Note: Both amount and item based subvention can not be applied together.
| ||||||||||||||||||||||||||||||||||||||||||||||||
simplifiedSubvention +
| |||||||||||||||||||||||||||||||||||||||||||||||||
simplifiedPaymentOffers Object optional | Object of Simplified Payment Offers. | ||||||||||||||||||||||||||||||||||||||||||||||||
simplifiedPaymentOffers +
| |||||||||||||||||||||||||||||||||||||||||||||||||
enablePaymentMode array of objects optional | "List of the payment modes which needs to be shown while making a payment. If the value is provided then only the listed payment modes are available for transaction. | ||||||||||||||||||||||||||||||||||||||||||||||||
enablePaymentMode +
| |||||||||||||||||||||||||||||||||||||||||||||||||
disablePaymentMode array of objects optional | List of the payment modes which need to disabled while making a payment. If the value provided then all the listed payment modes are unavailable for transaction. | ||||||||||||||||||||||||||||||||||||||||||||||||
disablePaymentMode +
| |||||||||||||||||||||||||||||||||||||||||||||||||
linkOrderId string optional | The Unique reference ID of the Order. It is alphanumeric and max length is 50 characters. Note: This link order id variable can be used for reconciliation purpose. Also we allow one payment on such link (success or failed).
| ||||||||||||||||||||||||||||||||||||||||||||||||
singleTransactionOnly boolean optional | Set this variable if you want only one order to be created on this link | ||||||||||||||||||||||||||||||||||||||||||||||||
simplifiedUnifiedOffers object conditional | Object of Simplified Unified Offer to apply offers on a transaction. | ||||||||||||||||||||||||||||||||||||||||||||||||
simplifiedUnifiedOffers +
|
Response Attributes
Head
Attribute | Description |
---|---|
timestamp string(15) | EPOCH timestamp of the time at which response is being sent. |
clientId string(3) | Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key. Example: C11 |
version string(2) | Version of the API passed in the request. |
channelId string(3) | The parameter value identifies the Channel for which API call is initiated. Possible values:
WEB
,
For websites, the value to be passed should be "WEB"
WAP
For Mobile websites/App, the value to be passed should be "WAP"
|
tokenType string | This parameter identifies whether the API works on checksum authentication. The value to be sent in tokenType is 'AES' for this API. |
Body
Attribute | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
resultInfo object | This parameter gives the information about the result of the API response | ||||||||||
ResultInfo +
| |||||||||||
linkId long | Unique Identifier for each Link | ||||||||||
merchantRequestId string | Unique Identifier as passed by merchant | ||||||||||
longUrl long | Payment Link URL. Not to be shared with the customer | ||||||||||
shortUrl string | Smart Payment Link URL. This should be shared with the customer | ||||||||||
linkType string | Type of link Example: FIXED, GENERIC, INVOICE | ||||||||||
amount double | Amount of Link | ||||||||||
lsActive boolean | Only Active Links can be used by customers to pay | ||||||||||
expiryDate string | Link would get expired after this time. Customers would no longer use this link to complete payment. | ||||||||||
merchantHtml string | This can be used to create a ‘Pay with Paytm’ button on merchant App & Website. Please embed this HTML behind the button | ||||||||||
createdDate string | Date & Time of Creation of the Link | ||||||||||
status string | Link Creation Status | ||||||||||
notificationDetails array | Details require to send link via SMS and Email to the customer. Customer Name is mandatory | ||||||||||
NotificationDetails +
|
Response Codes & Messages
resultCode | resultStatus | resultMessage |
---|---|---|
200 | SUCCESS | Success |
100 | FAILED | Error is dependent on what risk send us |
404 | FAILED | Data Not Found |
501 | FAILED | Internal Server Error |
502 | FAILED | Unknown Error Occurred |
5004 | FAILED | empty merchant Id. |
5005 | FAILED | Depending upon the use case the result message could be one from the following list:
|
5006 | FAILED | Link Description should be from 3 to 30 characters. |
5007 | FAILED | link name contains special character. |
5008 | FAILED | Payment amount is mandatory for Fixed Link |
5009 | FAILED | Amount should be greater than equal to Rs 1 |
5010 | FAILED | Expiry date is mandatory for Invoice Link Type |
5011 | FAILED | Empty Invoice Id for Invoice type Payment Link |
5012 | FAILED | Amount cannot be empty for invoice link |
5013 | FAILED | Invoice details cannot be greater than 50 |
5014 | FAILED | The amount sent in the request does not match the total amount of the invoice items. |
5015 | FAILED | This invoice ID has already been used for your account. Enter a new invoice ID |
5016 | FAILED | Product name cannot be blank |
5017 | FAILED | Product Name should be from 3 to 30 characters. |
5018 | FAILED | Amount cannot be less than 0 |
5019 | FAILED | Number of units cannot be less than or equal to 0 |
5020 | FAILED | Tax amount cannot be less than 0 |
5021 | FAILED | Expiry date is invalid. |
5022 | FAILED | Merchant not allowed payment forms |
5023 | FAILED | Merchant Id is invalid. |
5024 | FAILED | Invalid child MID |
5025 | FAILED | Invalid Merchant ID. Mentioned ID is not linked to Aggregator. |
5027 | FAILED | Expiry date cannot be set as more than 365 days from the current date |
5028 | FAILED | Checksum provided is invalid. |
5029 | FAILED | Depending upon the use case the result message could be one from the following list:
|
5030 | FAILED | request head cannot be empty |
5005 | FAILED | link name cannot be blank |
5033 | FAILED | Link Description should not contain any special characters |
5050 | FAILED | Invoice phone number is invalid |
5051 | FAILED | Invoice email id is invalid |
5052 | FAILED | Invalid mid type |
5053 | FAILED | invalid mid length |
curl -X POST 'https://securegw-stage.paytm.in/link/create' \
--header 'Content-Type: application/json' \
--data '{"body":{"mid":"{mid}","linkType":"GENERIC","linkDescription":"Test Payment","linkName":"Test"},"head":{"tokenType":"AES","signature":"{signature}"}}'