POSTOffer Discovery API

Use Case

Offer Discovery API can help the merchant discover Bank offers and Subvention campaigns configured with Paytm. With the help of this API:-

Both Amount and Item-based bank offers and subvention campaigns can be retrieved
The offers can be retrieved on all the desired payment instruments by passing them in the payMethods

Request Attributes

Content Type : JSON

Head

Attribute	Description
token string mandatory	Authorization string corresponding to the tokenType used. Example: 739816707d7444XXXXXXXX6cb4264d0a1590145379323
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, , TXN_TOKEN To be used incase authentication is done using TXN_TOKEN i.e, the unique transaction token received in the response of Initiate Transaction API or Initiate Subscription API. It is valid for 15 minutes.
channelId string 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"

Body

Attribute

Description

items

List<Object>

conditional

List of items on which offers have to be retrieved

Note: Required for items based offers not required for amount based offers

Items

Attribute	Description
id string mandatory	Identifier for every item generated by the merchant Eg: 105, item123
productId string mandatory	Unique product identifier for the merchant for item/product/SKU. Eg: PHONE1234XW Note: This can be alphanumeric value.
brandId string mandatory	Brand identifier of the product for the merchant. (LG, Sony etc). Should be sent in the request if bank offers/subvention plans are configured with brand attribute. Eg: "123" Note: Currently only numeric values are supported
categoryId string mandatory	Product category identifiers for the merchant (categories can be Electronics, foot wears etc). Should be sent in the request if bank offers/subvention plans are configured with category attribute. Eg. "123" Note: Currently only numeric values are supported
price double mandatory	Price of the product in rupees. Eg: "1000.00"

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

paymentDetails

object

mandatory

List of payment methods for which offers have to be retrieved

paymentDetails

Attribute

Description

orderAmount

double

mandatory

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

paymentOptions

List<Object>

mandatory

The payment options on which offers have to be retrieved

paymentOptions

Attribute

Description

issuingBank

string

optional

Code of the bank provided here.

Note: Can be sent for CC, DC, EMI, EMI_DC

Ex: ICICI

issuingNetworkCode

string

optional

Card scheme for which offers have to be retrieved.

Note: Can be sent for CC, DC, EMI, EMI_DC

Ex : VISA

payMethod

string

mandatory

Name of Payment Method.

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

vpa

string

optional

Virtual Payment Address for UPI payment method

tenure

List<Object>

optional

EMI tenures on which offers are to be retrieved

Note: It can be sent for EMI, EMI_DC

tenure

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

optional

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.

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

discoveryLiteResponse

boolean

optional

For a lighter version of offer details without calculation, this flag can be set to true.
Default: false

Response Attributes

Content Type : JSON

Head

Attribute	Description
requestId string	Unique reference ID which is given in request payload
responseTimeStamp string(15)	EPOCH timestamp of the time at which request is being sent. Example: 1588402269
version string(4)	Version of the API Example: v2
mid string(20)	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

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.
resultStatus string	This parameter indicates the status of API call. Possible Values: S ,F
resultMsg string	This parameter is the result message which contains information about the result.

paymentDetails

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

benefitText

string

Provides information regarding the benefit that user will avail on using the specific paymethod/ paymethod + issuing bank.

Eg: "Instant Discount"

benefit

boolean

Indicates if the user will avail any offer benefit using the specific paymethod/ paymethod + issuing bank

payMethod

string

Name of payment method.

error

Object

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 and 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.

offer Details

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

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

Response Codes & Messages

resultCode	resultStatus	resultMsg
1001	F	Request parameters are not valid
0001	F	Failed
1006	F	Your session has expired
2005	F	Checksum provided is invalid
1002	F	Token validation failed
0002	F	No Offers Available

⇾

Staging

Production

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

REQUEST

RESPONSE

CURL

JAVA

NODE

PHP

PYTHON

DOTNET

curl --location 'https://securestage.paytmpayments.com/theia/api/v1/offerDiscovery?referenceId=jsRef_20230613134141' \
--header 'Content-Type: application/json' \
--data '{"body":{"items":[{"id":"1234586674","productId":"1","brandId":"10002","categoryId":"10001","price":10000}],"mid":"YOUR_MID_HERE","paymentDetails":{"orderAmount":10000,"paymentOptions":[{"payMethod":"EMI"}]}},"head":{"channelId":"WEB","token":"{CHECKSUM}","tokenType":"CHECKSUM"}}'