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

Body

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

Name of the customer

customerEmail
string
optional

Email id of the customer

customerMobile
string
optional

Mobile Number of the customer.

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
Mandatory linkType: INVOICE

expiryDate
string
conditional

Link expiry date 
Supported Formats: "dd/mm/yyyy hh:mm:ss" or "dd/mm/yyyy"
Mandatory if 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

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

Split method

Possible Values: AMOUNT, PERCENTAGE

splitInfo
object
optional

List for child vendor merchant mid's and their split info

SplitInfo
+
AttributeDescription
mid
string
optional

Child mid

amount
object
conditional

Share of child vendor in the split by amount base
Use: Only splitMethod is AMOUNT

Amount
+
AttributeDescription
value
string
mandatory

This parameter contains the amount to be charged to the customer and can have two places of decimal.
Example: 1.00

currency
string
mandatory

This parameter indicates the currency in which transaction amount is to be deducted.
Possible Values: INR

percentage
string
conditional

Share of child vendor in the split by percentage base
Use: Only splitMethod is PERCENTAGE

extendInfo
string
optional

This contains the Map which needs to be sent by merchant (ref1, ref2,...,ref12) and contains keys (ref1, ref2,...,ref12) and their corresponding value

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.
This object needs to be passed in case of EMI subvention integration

Note: Both amount and item based subvention can not be applied together.

 

simplifiedSubvention
+
AttributeDescription
customerId
string
optional

Customer id

subventionAmount
string
conditional

Amount on which subvention is to be applied for amount based validation (Mandatory for amount based subvention).

items
Object
conditional

Items for subvention (Mandatory for product based subvention).

items
+
AttributeDescription
quantity
string
mandatory

Quantity of the product

productId
string
mandatory

Unique product identifier for the merchant.

price
string
mandatory

Cumulative price of the product (multiplied by quantity).

brandId
string
mandatory

Product brand identifier for the merchant e.g. LG, Sony etc. Should be send in the request if EMI plans are configured with brand attribute.

categoryList
List
mandatory

Product category identifiers for the merchant (categories can be Electronics, footwears etc). This should be sent in the request with same value which is configured in the EMI plan.

model
string
optional

Model id of the product. This should be sent if the merchant's EMI plans are configured with model attribute.

id
string
mandatory

Any unique identifier for one item in the request e.g. in case of 2 items in the cart, the values can be sent as 1234 and 1236.

simplifiedPaymentOffers
Object
optional

Object of Simplified Payment Offers.
Example: { "promoCode":"TESTXXWALLET","applyAvailablePromo":"true" }

simplifiedPaymentOffers
+
AttributeDescription
promoCode
string
optional

It is the code that has been applied during the transaction on the merchant website.
Example: TESXXXOMO

applyAvailablePromo
string
optional

Default Promo to be applied.
Possible Values: true, false
Default: true

cartDetails
object
conditional

SKU detail on which the Promo Code has to be applied.
 

Note: This is mandatory for SKU/Item based offer.

 

cartDetails
+
AttributeDescription
items
Array of Objects
mandatory

List of items

items
+
AttributeDescription
id
string
optional

Identified for every item generated by the merchant
Eg: “105”

amount
string
mandatory

Price of the product
Eg:  "amount": “150”

productDetail
Object
mandatory

Information to identify the item

productDetail
+
AttributeDescription
id
string
mandatory

Product identifier configured in the bank offer
Eg:  "id": "123400232343411113e331"

Note: This is the same value as passed in model attribute of simplifiedSubvention object in initiateTransaction API.

 

brandId
string
mandatory

Brand identifier configured in the bank offer
Eg:  "brandId": "1102" for Apple products

Note: Currently only numeric values are supported

 

categoryIds
Array of Strings
mandatory

Category identified configured in the bank offer
Eg:  [ "521" ] for iPhones

Note: Currently only numeric values are supported

 

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.
Example: [{""mode"" : ""UPI"", ""channels"" : [""UPIPUSH""]}]"

enablePaymentMode
+
AttributeDescription
mode
string
optional

Mode of payment enabled

channels
Array of strings
optional

Channel associated with mode.

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.
Example: [{"mode" : "UPI", "channels" : ["UPIPUSH"]}]

disablePaymentMode
+
AttributeDescription
mode
string
optional

Mode of payment disabled

channels
Array of strings
optional

Channel associated with mode.

linkOrderId
string
optional

The Unique reference ID of the Order. It is alphanumeric and max length is 50 characters.
Example: OREDRID_98765
 

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.
Either simplifiedUnifiedOffers object or unifiedOffersToken will have to be passed in case of offer integration.

simplifiedUnifiedOffers
+
AttributeDescription
promoDetails
object
conditional

Object to be passed for applying bank offer

promoDetails
+
AttributeDescription
applyAvailablePromo
boolean
optional

Default Promo to be applied.
Possible Values: true, false
Default: true

validatePromo
boolean
optional

To validate Promo to be applied and fail transaction accordingly.
Possible Values: true, false
Default: false

isAmountBasedBankOffer
boolean
optional

To run amount based bank offer, send this as true. Else send this as false.

Possible Values: true, false

Default: true

offerId
string
conditional

It is the identifier for the offer that has been applied during the transaction on the merchant website.
Example: 2134516

promoAmount
Double
optional

The amount eligible for applying offer/promo. Can be used incase the offer has to be applied on partial transaction amount

subventionDetails
object
conditional

Object to be passed for applying EMI Subvention

subventionDetails
+
AttributeDescription
pgPlanId
string
optional

EMI plan id needs to be sent only in those cases where you either keep the plan ids data at your end or receive the same in any API response.

Example: ICICI|3

Note: This param need not be send for EMI subvention integration through All-in-one SDK or JS checkout

 

isAmountBasedSubvention
boolean
optional

To run amount based subvention send this as true. Else send this as false.

Possible Values: true, false

Default: true

subventionAmount
double
conditional

Amount on which subvention is to be applied for amount based validation (mandatory for amount based subvention).

offerId
string
conditional

OfferId that is enabled on the product (mandatory for amount based subvention).

items
object
optional

List of items

item
+
AttributeDescription
id
string
mandatory

Any unique identifier for one item in the request e.g. in case of 2 items in the cart, the values can be sent as 1234 and 1236.

productId
string
mandatory

Unique product identifier for the merchant.

brandId
string
mandatory

Product brand identifier for the merchant
Example: LG, Sony etc. Should be send in the request if EMI plans are configured with brand attribute.

categoryId
string
mandatory

Product category identifier for the merchant (categories can be Electronics, footwears etc). This should be sent in the request with same value which is configured in the EMI plan.

price
Integer
mandatory

Price of the product

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
string

This parameter identifies whether the API works on checksum authentication. The value to be sent in tokenType is 'AES' for this API.

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