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

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

Attribute

Description

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

Attribute

Description

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

Attribute

Description

emiOfferDetails

Object

conditional

EMI Subvention offer intent to be passed for offer application

emiOfferDetails

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

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

Attribute

Description

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

Attribute

Description

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

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

Attribute	Description
unit string optional	Possible values: MONTH or DAYS
value Integer optional	Ex : 3 or 6 or 9

subventionAmount

double

optional

Amount on which subvention has to be applied. This can be used in case subvention has to be applied on partial transaction amount

boEligibleAmount

double

optional

Amount on which offer/promo has to be applied. This can be used in case offer/promo has to be applied on partial transaction amount

applyBankOffer

Boolean

conditional

Flag to pass the intent to apply a bank offer on a transaction. To be set to true incase the offer has to be applied on the transaction.

applySubvention

Boolean

conditional

Flag to pass the intent to apply subvention on a transaction. To be set to true in case subvention has to be applied on the transaction.

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

Attribute

Description

emiOfferDetails

Object

conditional

EMI Subvention offer intent to be passed for offer application

emiOfferDetails

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

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

amountBasedBankOffer

boolean

conditional

Flag to identify the type of offer to applied i.e, Amount based or SKU based offer. Mandatory to be sent as false for item based offer
Default: true

amountBasedSubvention

boolean

conditional

Flag to identify the type of subvention to applied i.e, Amount based or SKU based subvention. Mandatory to be sent as false for item based subvention
Default: true

Response Attributes

Content Type : JSON

Head

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

Attribute

Description

ResultInfo

Object

This parameter gives information about the result of the API response

resultInfo

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

Attribute

Description

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

Attribute	Description
errorCode string	Error code.
errorMessage string	Error Message.

tenureDetails

Object

Tenure wise list of applicable offers on EMI/EMI_DC

tenureDetails

Attribute

Description

tenure

Object

EMI tenure information

tenure

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

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

Attribute

Description

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

Attribute

Description

emiOfferDetails

Object

Detailed information of EMI Subvention applicable on the item

emiOfferDetails

Attribute

Description

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

Attribute

Description

value

string

Amount of gratification

type

string

Type of gratification, its value can be DISCOUNT or CASHBACK

info

object

Offer Gratification information

info

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

Composition of gratification provided by various entities such as brand, merchant, bank etc.

amountBearer

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

Attribute

Description

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

Attribute

Description

value

string

Amount of gratification

type

string

Type of gratification, its value can be DISCOUNT or CASHBACK

info

object

Offer Gratification information

info

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

Composition of gratification provided by various entities such as brand, merchant, bank etc.

amountBearer

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

Attribute

Description

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

Attribute

Description

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

Attribute

Description

emiOfferDetails

Object

Detailed information of EMI Subvention applicable on the item

emiOfferDetails

Attribute

Description

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

Attribute

Description

value

string

Amount of gratification

type

string

Type of gratification, its value can be DISCOUNT or CASHBACK

info

Object

Offer Gratification information

info

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

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

Attribute

Description

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

Attribute

Description

value

string

Amount of gratification

type

string

Type of gratification, its value can be DISCOUNT or CASHBACK

info

Object

Offer Gratification information

info

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

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

resultCode	resultStatus	resultMsg
1001	F	Request parameters are not valid
0001	F	Failed
2005	F	Checksum provided is invalid
1006	F	Your session has expired
2100	F	Invalid Access Token
2004	F	SSO Token is invalid
0002	F	No Offers Available

⇾

Staging

Production

https://securestage.paytmpayments.com/theia/api/v1/offerApply copy icon

REQUEST

RESPONSE

CURL

JAVA

NODE

PHP

PYTHON

DOTNET

curl --location --request POST 'https://securestage.paytmpayments.com/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"}]}]}}}'