search

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 form template to the link using this API

Request Attributes

Content Type : JSON

Head

AttributeDescription
timestamp
string(15)
optional

EPOCH timestamp of the time at which request is being sent.
Example: 1588402269

tokenType
aes
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.
Note: Create the signature using the body parameter of the request.

Body

AttributeDescription
merchantRequestId
string
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
mandatory

Name of the link that merchant want to display to customer, linkName is used to generate long url.

linkDescription
string
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
+
AttributeDescription
customerName
string
optional

Name of the customer

customerEmail
string
optional

Email id of the customer

customerMobile
string
optional

Mobile Number of the customer.

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
int
optional

Attach a form specified by the template ID to your link

linkNotes
string
optional

Add additional notes to your link. This won’t be shown to your customers

invoiceId
string
conditional

Invoice number or unique id
Mandatory linkType:INVOICE

expiryDate
string
conditional

Link expiry date Format: d/m/Y
Mandatory linkType:INVOICE

invoicePhoneNo
string
optional

Merchant contact number

invoiceEmail
string
optional

Merchant email address

invoiceDetails
object
optional

Product details with price and tax

InvoiceDetails
+
AttributeDescription
productName
string
optional

Product name

productCode
string
optional

Product code

noOfUnits
string
optional

Number of quantity

perUnitAmount
string
optional

Per quantity amount value

perUnitTax
array
optional

Per quantity tax

PerUnitTax
+
AttributeDescription
taxName
string
optional

Name of tax

Example: GST, SGST

taxAmount
string
optional

Amount of tax

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

Response Attributes

Content Type : JSON

Head

AttributeDescription
timestamp
string(15)

EPOCH timestamp of the time at which response is being sent.
Example: 1588402269

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.
Example: v1

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
aes

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)

Body

AttributeDescription
resultInfo
object

This parameter gives the information about the result of the API response

ResultInfo
+
AttributeDescription
resultCode
string

This is the resultCode corresponding to a particular message and is returned to the merchant. It's maximum length is 64. The different result codes corresponding to this API are mentioned below.

resultStatus
string

This parameter indicates the status of API call.

 

Possible Values: SUCCESS, FAILED

resultMessage
string(256)

This parameter is the result message which contains information about the result.The different result messages corresponding to this API are mentioned below.
 

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
+
AttributeDescription
customerName
string

Name of the Customer which will be sent in the notification message

contact
string

Contact Number of customer where the notification will be sent

notifyStatus
string

Status of the notification

timestamp
string

Unix Timestamp of the response

Response Codes & Messages

resultCoderesultStatusresultMessage
200SUCCESSSuccess
100FAILEDError is dependent on what risk send us
404FAILEDData Not Found
501FAILEDInternal Server Error
502FAILEDUnknown Error Occurred
5004FAILEDempty merchant Id.
5005FAILED

Depending upon the use case the result message could be one from the following list:

  • empty link name.
  • link name cannot be blank
5006FAILEDLink Description should be from 3 to 30 characters.
5007FAILEDlink name contains special character.
5008FAILEDPayment amount is mandatory for Fixed Link
5009FAILEDAmount should be greater than equal to Rs 1
5010FAILEDExpiry date is mandatory for Invoice Link Type
5011FAILEDEmpty Invoice Id for Invoice type Payment Link
5012FAILEDAmount cannot be empty for invoice link
5013FAILEDInvoice details cannot be greater than 50
5014FAILEDThe amount sent in the request does not match the total amount of the invoice items.
5015FAILEDThis invoice ID has already been used for your account. Enter a new invoice ID
5016FAILEDProduct name cannot be blank
5017FAILEDProduct Name should be from 3 to 30 characters.
5018FAILEDAmount cannot be less than 0
5019FAILEDNumber of units cannot be less than or equal to 0
5020FAILEDTax amount cannot be less than 0
5021FAILEDExpiry date is invalid.
5022FAILEDMerchant not allowed payment forms
5023FAILEDMerchant Id is invalid.
5024FAILEDInvalid child MID
5025FAILEDInvalid Merchant ID. Mentioned ID is not linked to Aggregator.
5027FAILEDExpiry date cannot be set as more than 365 days from the current date
5028FAILEDChecksum provided is invalid.
5029FAILED

Depending upon the use case the result message could be one from the following list:

  • request body cannot be empty
  • empty request.
5030FAILEDrequest head cannot be empty
5005FAILEDlink name cannot be blank
5033FAILEDLink Description should not contain any special characters
5050FAILEDInvoice phone number is invalid
5051FAILEDInvoice email id is invalid
5052FAILEDInvalid mid type
5053FAILEDinvalid mid length
Staging
Production
https://securegw-stage.paytm.in/link/createcopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
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}"}}'
copy icon