paytm developer docs logoDeveloperDocumentation
search

POSTApply Promo API

Use Case

This API is used to apply the promotion/offer selected by the user for a particular transaction.

 

 

Query Params

ATTRIBUTE DESCRIPTION

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

referenceId

string
conditional

 This is the unique reference id and should have the same value as used in Access Token API.
Note: It becomes mandatory in case tokenType value is sent as ACCESS in the request.

Request Attributes

Content Type : JSON

Head

AttributeDescription
requestId
string
optional

Unique reference ID which is given in request payload

requestTimestamp
string(15)
optional

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

version
string(4)
optional

Version of the API.

Example: v2

channelId
string(3)
mandatory

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
mandatory

Authorization method for this request.

Possible values:
ACCESS
To be used in case authentication is done using accessToken and this is received in the response of Access Token API
,
CHECKSUM
To be used in case authentication is done using CHECKSUM
token
string
mandatory

Authorization string corresponding to the tokenType used.

Example: 739816707d7444XXXXXXXX6cb4264d0a1590145379323

Body

AttributeDescription
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

custId
string
optional

Unique reference ID for every customer which is generated by merchant. Special characters allowed in CustId are @, ! ,_ ,$, .

promocode
string
optional

Title of promocode,if blank Paytm will apply best offer on that merchant.

paymentOptions
object
mandatory

In case of hybrid it will have multiple objects.

PaymentOptions
+
AttributeDescription
transactionAmount
string
mandatory

Amount in rupees.

payMethod
string
mandatory

Name of Payment Method.

Possible Values: BALANCE, NET_BANKING, CREDIT_CARD, DEBIT_CARD,UPI, EMI_DC, EMI

bankCode
string
conditional

Code of the bank provided here.

Note: Becomes mandatory in case of PayMethod as NET_BANKING

cardNo
string
conditional

Card number present on your Debit/Credit Card.

Note: Becomes mandatory in case of PayMethod as CREDIT_CARD, DEBIT_CARD, EMI_DC, EMI

savedCardId
string
conditional

Paytm saved card Id unique for each card.

Note: Becomes mandatory in case of Saved Credit or Debit Card

vpa
string
conditional

This is needed for UPI transaction.

Note: Becomes mandatory in case of PayMethod as UPI

tenure
string
optional

The tenure on which the promocode is applicable.

Possible values = -1 and 3,6,9,12,24,48,36 etc

Send tenure = -1 to retrieve all the tenures on which the offer is applicable
 

totalTransactionAmount
string
mandatory

Sum of all the transaction amount in paymentOptions, in rupees.

cartDetails
Object
conditional

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

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

 

cardTokenInfo
object
optional

Token data required to process a token transaction.

cardTokenInfo
+
AttributeDescription
cardToken
string
mandatory

16 digits Token PAN

tokenExpiry
string
mandatory

Token expiry. Format: MMYYYY

TAVV
string
mandatory

Token Verification Value generated by the network valid for a single token card  payment

Note: This param is not required for Diners saved card payments
cardSuffix
string
mandatory

Last 4 digits of the actual card.

panUniqueReference
string
mandatory

The unique reference allocated to the Primary Account Number by the card network also known as PAR.

Note: Merchant can pass unique card identifier of their ecosystem if Network PAR is not available.
tokenUniqueReference
string
conditional

Token reference number is provided by the card or issuer for a given tokenization request.

This param is mandatory to process Diner Card Tokens

Possible Value: Any

merchantTokenRequestorId
string
conditional

Merchant's token requestor id provided by the Network or issuer

This param is mandatory to process Diner Card Tokens

Possible Value: Any

tokenType
string
mandatory

This parameter indicates whether the card transaction is a saved card transaction or a guest checkout transaction.

Possible Values: COFT/ALTERNATE

Note: In case of hybrid only, non wallet amount and details should be sent.

Response Attributes

Content Type : JSON

Head

AttributeDescription
requestId
string

Unique reference ID for a transaction which is generated by merchant.

responseTimestamp
string(15)

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

version
string(2)

Version of the API passed in the request.
Example: v1

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.

resultCodeId
string

Result code id returned to merchant.

resultStatus
string

This parameter indicates the status of API call.

Possible Values:
S
For Success

,

F
For Failure
resultMsg
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.

paymentOffers
object

Detail of payment offer.

PaymentOffer
+
AttributeDescription
totalInstantDiscount
Numeric string

Sum of instant discounts on all paymethod(Wallet+Other in case of hybrid) in rupees.

totalCashbackAmount
string

Sum of cashbacks on all paymethod(Wallet+Other in case of hybrid) in rupees.

offerBreakUp
object

Detail of offer being applied.

OfferBreakup
+
AttributeDescription
promocodeApplied
string

Promocode applied by the user.

promotext
string

Text message for promocode.

promoVisibility
string

Based on this flag frontend will show error message.In success this will be false.

responseCode
string

This will used by external merchants to display user messages for promo.

instantDiscount
Numeric string

Amount in rupees

cashbackAmount
Numeric string

Amount in rupees.

payMethod
string

Name of payment method.

Possible Values: BALANCE, BANK_EXPRESS, NET_BANKING, CREDIT_CARD, DEBIT_CARD,IMPS,ATM, EMI, COD, MP_COD, HYBRID_PAYMENT, UPI, PAYTM_DIGITAL_CREDIT, PREPAID_CARD, PPBL,LOYALTY_POINT, REFUND_MANUAL, EMI_DC, WALLET

applicableTenures
Array of strings

The tenures on which the promocode is applicable.

Possible values: [] and[ 3,6,9] etc

If applicable tenures: [], then the offer is applicable on all tenures configured for merchant 
 

cartDetails
Object

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

cartDetails
+
AttributeDescription
items
Array of Objects

List of items

items
+
AttributeDescription
id
string

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

amount
string

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

promocode
string

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

productDetail
Object

Information to identify the item

productDetail
+
AttributeDescription
id
string

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

brandId
string

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

categoryIds
Array of Object

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

Note: If no offer is active on the merchant then Paytm will send an error response ( i.e. resultStatus = "F" ). If merchant has active offers but no offer is applicable on payment instrument supplied Paytm will send success response ( i.e. resultStatus = "S" ) with proper message in promo text.

Response Codes & Messages

resultCoderesultStatusresultMsg
00000000 S Success
9999 F Something went wrong.
1012 F No promo code currently active on the merchant.
1001 F Request parameters are not valid.
1006 F Session expired
2005 F Checksum provided is invalid.
⇾
Staging
Production
https://securestage.paytmpayments.com/theia/api/v2/applyPromo?mid={mid}copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securestage.paytmpayments.com/theia/api/v2/applyPromo?mid={mid}' \
--header 'Content-Type: application/json' \
--data '{"body":{"mid":"{mid}","custId": "CUST_001","paymentOptions":[{"transactionAmount":"100","payMethod":"CREDIT_CARD","bankCode":"HDFC","cardNo":"4111111111111111"}],"totalTransactionAmount":"100"},"head":{"channelId":"WEB","tokenType":"CHECKSUM","token":"{CHECKSUM}"}}'
copy icon