search

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

AttributeDescription
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

AttributeDescription
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
+
AttributeDescription
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
+
AttributeDescription
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
+
AttributeDescription
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
+
AttributeDescription
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

AttributeDescription
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

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. 

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

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
+
AttributeDescription
errorCode
string

Error code.

errorMessage
string

Error Message.

tenureDetails
Object

Tenure wise list of applicable offers on EMI and 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

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

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

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

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.

offer Details
+
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

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

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

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

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

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

Response Codes & Messages

resultCoderesultStatusresultMsg
1001FRequest parameters are not valid
0001FFailed
1006FYour session has expired
2005FChecksum provided is invalid
1002FToken validation failed
0002FNo Offers Available
⇾
Staging
Production
https://securegw-stage.paytm.in/theia/api/v1/offerDiscoverycopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl --location 'https://securegw-stage.paytm.in/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"}}'

 

copy icon