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, 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

bankCode
string
optional

Code of the bank provided here.

cardNo
string
optional

Card number present on your Debit/Credit card.

savedCardId
string
optional

Paytm saved card Id unique for each card.

vpa
string
optional

This is needed for UPI transaction.

totalTransactionAmount
string
mandatory

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

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.

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://securegw-stage.paytm.in/theia/api/v2/applyPromo?mid={mid}copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/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