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

Attribute	Description
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

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

Attribute	Description
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

Attribute

Description

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

Attribute	Description
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

Attribute

Description

splitMethod

string

optional

Split method

Possible Values: AMOUNT, PERCENTAGE

splitInfo

object

optional

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

SplitInfo

Attribute

Description

mid

string

optional

Child mid

amount

object

conditional

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

Amount

Attribute	Description
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

Attribute

Description

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

Attribute	Description
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

Attribute

Description

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

Attribute

Description

items

Array of Objects

mandatory

List of items

items

Attribute

Description

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

Attribute	Description
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

Attribute	Description
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

Attribute	Description
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

Attribute

Description

promoDetails

object

conditional

Object to be passed for applying bank offer

promoDetails

Attribute	Description
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

Attribute	Description
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

Attribute	Description
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
bankOffers List of Strings optional	List of bank offers that can be applied on the item
emiOffer string optional	EMI Subvention offerId that is applicable on this item.

Response Attributes

Content Type : JSON

Head

Attribute	Description
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

Attribute

Description

resultInfo

object

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

ResultInfo

Attribute	Description
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

Attribute	Description
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

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: empty link name. link name cannot be blank
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: request body cannot be empty empty request.
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

⇾

Staging

Production

https://securegw-stage.paytm.in/link/create copy 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}"}}'