search

POSTApply Offer API

Use Case

Paytm Apply Offer API is used to apply bank offer and subvention offer on the transaction.

Request Attributes

Content Type : JSON

Head

AttributeDescription
token
string
conditional

Authorization string corresponding to the tokenType used.

Note: It is mandatory for token type CHECKSUM, SSO/ACCESS

tokenType
string
mandatory

Authorization method for this request.

Example: TXN_TOKEN/ACCESS/SSO/CHECKSUM

txnToken
string
conditional

This is the unique transaction token received in the response of Initiate Transaction API. It is valid for 15 minutes.

Note: It is mandatory for token type TXN_TOKEN
Example: f0bed899539742309eebd8XXXX7edcf61588842333227

channelId
string
mandatory

The parameter value identifies the Channel for which API call is initiated.

Example: WEB/WAP

Body

AttributeDescription
items
List<Object>
conditional

List of items on which offers have to be applied.

Note: It is required for items based offers not required for amount based offers

items
+
AttributeDescription
id
string
mandatory

Identifier for every item generated by the merchant.

Eg: 105, item123

productId
string
mandatory

Unique product identifier for the merchant.
Note: This can be an alphanumeric value

E.g. it can be a sku for a product

brandId
string
mandatory

Brand identifier of the product for the merchant should be sent in the request if the bank offers/subvention plans are configured with brand attribute.
Note: Currently only numeric values are supported.

E.g. LG, Sony etc. 

categoryId
string
mandatory

Product category identifiers for the merchant should be sent in the request if the bank offers/subvention plans are configured with category attributes.
Note: Currently only numeric values are supported.

E.g. Categories can be Electronics, foot wears etc. 

price
double
mandatory

Price of the product 

offerDetails
Object
mandatory

Offers which must be applied on the transaction

offerDetails
+
AttributeDescription
emiOfferDetails
Object
conditional

EMI Subvention offer intent to be passed for offer application

emiOfferDetails
+
AttributeDescription
offerId
string
mandatory

OfferId of the EMI campaign to be applied. It can be retrieved from the response of Offer Discovery API by passing paymethod, issuingBank, issuingBankNetwork

bankOfferDetails
Array of Object
conditional

Bank offer intent to be passed for offer application. 

Note: To be sent when a specific bank offer is to be applied

bankOfferDetails
+
AttributeDescription
offerId
string
mandatory

OfferId of the Bank offer to be applied. It can be retrieved from the response of Offer Discovery API by passing paymethod and/or  issuingBank 

mid
string
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.

orderId
string
optional

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

paymentDetails
Object
mandatory

List of payment methods for which offers have to be applied

paymentDetails
+
AttributeDescription
orderAmount
double
mandatory

Transaction Amount in Rupees. Sum of the prices of all the items

paymentOptions
Object
mandatory

Payment details corresponding to the instrument to be used by the user for the transaction

paymentOptions
+
AttributeDescription
issuingBank
string
conditional

Code of the bank is provided here.

Note: It is mandatory for Net Banking

Example: ICICI

issuingNetworkCode
string
optional

Card scheme for which offers have to be retrieved.

Note: It can be sent for CC, DC, EMI, EMI_DC
Example: VISA

payMethod
string
mandatory

Name of Payment Method.
Possible Values: BALANCE, NET_BANKING, CREDIT_CARD, DEBIT_CARD,UPI, EMI_DC, EMI

vpa
string
conditional

Virtual Payment Address for UPI payment method.

Note: It is mandatory for UPI

bin
String (Max length 9)
conditional

Starting 6 digits of credit or debit card number (Either card number or cardBin should be sent).

Note: It is mandatory in case of SavedCardId and cardTokenInfo
Example: 411111

cacheCardToken
string
optional

Token data required to process transactions. Generated in express flows.

cardNo
string
conditional

Card number

Note: It is mandatory for CC, DC, EMI, EMI_DC. Also, for CC, DC, EMI, EMI_DC any one of cardNo, savedCardId, cardTokenInfo, or (Bin and cacheCardToken) is mandatory.
Example: "|4111111111111111|111|012025"

savedCardId
string
conditional

Unique Card ID provided by Paytm for a saved card.

Note: It becomes mandatory in case of Saved Credit, Debit Card, CC, DC, EMI, and EMI_DC. Also, for CC, DC, EMI, EMI_DC any one of cardNo, savedCardId, cardTokenInfo or (Bin and cacheCardToken) is mandatory .

cardTokenInfo
Object
conditional

Token data is required to process a card token-based transaction.

Note: It is mandatory for CC, DC, EMI, EMI_DC. Also, for CC, DC, EMI, EMI_DC any one of cardNo, savedCardId, cardTokenInfo or (Bin and cacheCardToken) is mandatory

cardTokenInfo
+
AttributeDescription
cardToken
string
mandatory

16 digits Token PAN

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.

tenures
Object
conditional

The EMI tenure selected by the user on which offers have to be applied.

tenures
+
AttributeDescription
unit
string
optional

Possible values: MONTH or DAYS

value
Integer
optional

Ex : 3 or 6 or 9

custId
string
optional

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

offerDetails
Object
conditional

Offer details object to be passed only for amount-based offers. 

Note: OfferDetails along with items can not be passed. Also, It is required only for Amount based offers.

offerDetails
+
AttributeDescription
emiOfferDetails
Object
conditional

EMI Subvention offer intent to be passed for offer application

emiOfferDetails
+
AttributeDescription
offerId
string
mandatory

OfferId of the EMI campaign to be applied. It can be retrieved from the response of Offer Discovery API by passing paymethod, issuingBank, issuingBankNetwork

bankOfferDetails
Array of Object
conditional

Bank offer intent to be passed for offer application. 

Note: To be sent when a specific bank offer is to be applied

bankOfferDetails
+
AttributeDescription
offerId
string
mandatory

OfferId of the Bank offer to be applied. It can be retrieved from the response of Offer Discovery API by passing paymethod and/or  issuingBank 

Response Attributes

Content Type : JSON

Head

AttributeDescription
requestId
string

Unique reference ID which is given in request payload

responseTimeStamp
string

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

version
string

Version of the API
Example: v2

Body

AttributeDescription
ResultInfo
Object

This parameter gives information about the result of the API response

resultInfo
+
AttributeDescription
resultStatus
string

This parameter is the result specific to the phase of the transaction mentioned in the txnType field

resultCode
string

This is the resultCode corresponding to a particular message and is returned to the merchant. It's maximum length is 64.

resultMsg
string

This parameter is the result message which contains information about the result.

paymentDetails
Object

List of payment methods having offer details

paymentDetails
+
AttributeDescription
issuingBank
string

Code of the bank is provided here.

Ex: ICICI

bankName
string

Issuing Bank Name

Ex: ICICI Bank

bankLogo
string

URL of the bank logo 

payMethod
string

Name of payment method.

cardType
string

Type of the card - Credit card, Debit Card

benefitText
string

Provides information regarding the benefit that user will avail on using the specific paymethod/ paymethod + issuing bank. Eg: "Instant Discount"

error
Object

It is returned in case no offers available for this pay method.

error
+
AttributeDescription
errorCode
string

Error code.

errorMessage
string

Error Message.

tenureDetails
Object

Tenure wise list of applicable offers on EMI/EMI_DC

tenureDetails
+
AttributeDescription
tenure
Object

EMI tenure information

tenure
+
AttributeDescription
value
Integer

EMI interval in months e.g. 3, 6, 9, 12 etc.

unit
string

Ex: Months

roi
Double

Rate of interest in percentage charged by the bank of the specific tenure

error
Object

Returned in case no offers available for this pay method.

error
+
AttributeDescription
errorCode
string

Error code.

errorMessage
string

Error Message.

effectiveAmount
Double

Final price/cost applicable to the user after applying all offers.

loanAmount
Double

The final amount at which loan would be booked after discounting the bank offers and subventions applicable

originalAmount
Double

Original price of the product

payableAmount
Double

The amount to be paid while making the transaction.

totalPayableAmount
Double

Total Amount to be paid by the user to purchase the product(payable amount + interest).

planId
string

EMI plan id Eg. "planId": "HDFC|6".

Note: This planId data can be used for applying offer by passing in the request
items
Object

List of items sent in the request. Each item would have the specific bank offers/subvention applicable against the payment instrument.

items
+
AttributeDescription
id
string

Identifier for every item generated by the merchant sent in the request for an item i.e, for a brandId+ category Id + productId

offerDetails
object

Detailed information of the offers applicable on the item

offerDetails
+
AttributeDescription
emiOfferDetails
Object

Detailed information of EMI Subvention applicable on the item

emiOfferDetails
+
AttributeDescription
offerId
string

ID of the offer. This is a numeric value which can be passed for applying offer in the API request

type
string

Type of the EMI Subvention on the basis of contributor

Ex: MERCHANT, BRAND

emiType
string

Type of EMI on the basis of subvention

Possible Values: SUBVENTION or STANDARD.

subventionType
string

Type of Subvention gratification provided

Possible Values: LOW_COST, NO_COST

emi
Double

Effective EMI cost per month for the item.

interest
Double

Interest amount charged by the bank for the EMI

tnc
string

URL for the document containing terms and conditions of the subvention offer

offerText
string

Offer text description

Eg: ₹500.0 discount applied successfully.

minPrice
Double

Minimum Transaction Amount for which the offer is applicable

maxPrice
Double

Maximum Transaction Amount for which the offer is applicable

validUpto
string

Start date of the offer campaign

validFrom
string

End date of the offer campaign

gratifications
Object

Gratifications available for the plan

gratifications
+
AttributeDescription
value
string

Amount of gratification

type
string

Type of gratification, its value can be DISCOUNT or CASHBACK

info
object

Offer Gratification information

info
+
AttributeDescription
type
string

EX: ABSOLUTE/PERCENTAGE

value
Integer

Value of the gratification that can be availed in terms of percentage or absolute monetary value

cap
Integer

Max Benefit Allowed as configured by the merchant (In Paise)

amountBearer
object

(Do we need this in discovery API - currently we are not passing this as part of response).

amountBearer
+
AttributeDescription
brand
double

Amount borne by the brand in the gratification provided

merchant
double

Amount borne by merchant in the gratification provided

bank
double

Amount borne by bank in the gratification provided

platform
double

Amount borne by platform in the gratification provided

bankOfferDetails
string

Detailed information of the bank offer applicable on the item

bankOfferDetails
+
AttributeDescription
offerId
string

ID of the offer. This is a numeric value which can be passed for applying offer in the API request

type
string

Type of the Bank Offer on the basis of contributor 
 

Ex: MERCHANT, BRAND, BANK

promoCode
string

Promo code configured on the offer applicable. This is an alphanumeric value which can be passed for applying offer in the API request

tnc
string

URL for the document containing terms and conditions of the bank offer

offerText
string

Offer text description

Eg: ₹500.0 discount applied successfully.

validUpto
string

Start date of the offer campaign

validFrom
string

End date of the offer campaign

gratifications
Object

Gratifications available

gratifications
+
AttributeDescription
value
string

Amount of gratification

type
string

Type of gratification, its value can be DISCOUNT or CASHBACK

info
object

Offer Gratification information

info
+
AttributeDescription
type
string

EX: ABSOLUTE/PERCENTAGE

value
Integer

Value of the gratification that can be availed in terms of percentage or absolute monetary value

cap
Integer

Max Benefit Allowed as configured by the merchant (In Paise)

amountBearer
object

(Do we need this in discovery API - currently we are not passing this as part of response).

amountBearer
+
AttributeDescription
brand
double

Amount borne by the brand in the gratification provided

merchant
double

Amount borne by merchant in the gratification provided

bank
double

Amount borne by bank in the gratification provided

platform
double

Amount borne by platform in the gratification provided

offerDetails
Object

List of bank offers applicable on the different payMethods. Will be returned for all the payment methods except EMI and EMI_DC.

offerDetails
+
AttributeDescription
effectiveAmount
Double

Final price at which the user gets the product

payableAmount
Double

Amount paid by the user to complete the transaction

items
Object

List of items sent in the request. Each item would have the specific bank offers/subvention applicable against the payment instrument.

items
+
AttributeDescription
id
string

Identifier for every item generated by the merchant sent in the request for an item i.e, for a brandId+ category Id + productId

offerDetails
Object

Detailed information of the offers applicable on the item

offerDetails
+
AttributeDescription
emiOfferDetails
Object

Detailed information of EMI Subvention applicable on the item

emiOfferDetails
+
AttributeDescription
offerId
string

ID of the offer. This is a numeric value which can be passed for applying offer in the API request

emiType
string

Type of EMI on the basis of subvention
Possible Values: SUBVENTION or STANDARD.

subventionType
string

Type of Subvention gratification provided
Possible Values: LOW_COST, NO_COST

emi
Double

Effective EMI cost per month for the item.

interest
Double

Interest amount charged by the bank for the EMI

tnc
string

URL for the document containing terms and conditions of the subvention offer

offerText
string

Offer text description
Eg: ₹500.0 discount applied successfully.

gratifications
Object

Gratifications available for the plan

gratification
+
AttributeDescription
value
string

Amount of gratification

type
string

Type of gratification, its value can be DISCOUNT or CASHBACK

info
Object

Offer Gratification information

info
+
AttributeDescription
type
string

EX: ABSOLUTE/PERCENTAGE

value
Integer

Value of the gratification that can be availed in terms of percentage or absolute monetary value

cap
Integer

Max Benefit Allowed as configured by the merchant (In Paise)

amountBearer
object

Contribution of different entities in the offer gratification 

amountBearer
+
AttributeDescription
brand
double

Amount borne by the brand in the gratification provided

merchant
double

Amount borne by merchant in the gratification provided

bank
double

Amount borne by bank in the gratification provided

platform
double

Amount borne by platform in the gratification provided

bankOfferDetails
Object

Detailed information of the bank offer applicable on the item

bankOfferDetails
+
AttributeDescription
offerId
string

ID of the offer. This is a numeric value which can be passed for applying offer in the API request

promoCode
string

Promo code configured on the offer applicable. This is a numeric value which can be passed for applying offer in the API request

tnc
string

URL for the document containing terms and conditions of the bank offer

offerText
string

Offer text description
Eg: ₹500.0 discount applied successfully.

gratifications
Object

Gratifications applicable on the transaction

gratifications
+
AttributeDescription
value
string

Amount of gratification

type
string

Type of gratification, its value can be DISCOUNT or CASHBACK

info
Object

Offer Gratification information

info
+
AttributeDescription
type
string

EX: ABSOLUTE/PERCENTAGE

value
Integer

Value of the gratification that can be availed in terms of percentage or absolute monetary value

cap
Integer

Max Benefit Allowed as configured by the merchant (In Paise)

amountBearer
object

Contribution of different entities in the offer gratification 

amountBearer
+
AttributeDescription
brand
double

Amount borne by the brand in the gratification provided

merchant
double

Amount borne by merchant in the gratification provided

bank
double

Amount borne by bank in the gratification provided

platform
double

Amount borne by platform in the gratification provided

unifiedOffersToken
string

Token which is generated when merchant intends to apply offers in the payment on the passed instrument of the customer. It will be needed to send in the Initiate Transaction API request.

Response Codes & Messages

resultCoderesultStatusresultMsg
1001FRequest parameters are not valid
0001FFailed
2005FChecksum provided is invalid
1006FYour session has expired
2100FInvalid Access Token
2004FSSO Token is invalid
0002FNo Offers Available
Staging
Production
https://securegw-stage.paytm.in/theia/api/v1/offerApplycopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl --location --request POST 'https://securegw-stage.paytm.in/theia/api/v1/offerApply?referenceId=123456789' \
--header 'Content-Type: application/json' \
--data '{ "head": { "channelId": "WEB", "tokenType": "CHECKSUM", "token": {CHECKSUM}},
    "body": {"mid": "YOUR_MID_HERE", "custId": "1000177185", "items": [{"id": "123", "productId": "8903287020ABC", "brandId": "123","categoryId": "1234", "price": 8000.25,"offerDetails": { "emiOfferDetails": { "offerId": "2130582" },  "bankOfferDetails": [{"offerId": "2126546"} ] }  } ], "paymentDetails": { "orderAmount": 8000.25, "paymentOptions": [{"issuingBank": "HDFC","issuingNetworkCode": "VISA","payMethod": "EMI","cardNo":"4111111111111111","tenure": [{ "value": 6,"unit": "MONTH"}]}]}}}'

 

copy icon