POSTValidate API - EMI Subvention

Use Case

This api validates the dynamic conditions on the payment gateway page. Merchant needs to send one of the cacheCardtoken and cardNumber

Request Attributes

Content Type : JSON

Head

Attribute	Description
channelId string(3) optional	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"
requestId string(32) mandatory	Unique reference ID for a transaction which is generated by merchant and sent in the request
requestTimestamp string(15) mandatory	EPOCH timestamp of the time at which request is being sent. Example: 1588402269
version string(4) mandatory	Version of the API. Example: v1
tokenType string mandatory	This is for authentication method. For SSO token authentication, the value is SSO. For checksum authentication, the value is CHECKSUM.
token string mandatory	For tokenType SSO, use SSO Token of Paytm User. For tokenType CHECKSUM, It's value to be sent should be the checksum string created by using Paytm checksum library. Note: Create the checksum using the body parameter of the request.

Body

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

planId

string

mandatory

ID of the plan

items

object

mandatory

Item list sent for EMI

For Item based only

Items

Attribute

Description

string

mandatory

Any unique identifier for one item in the request e.g. in case of 2 items in the cart, the values can be sent as 1234 and 1236.

productId

string

mandatory

Unique product identifier for the merchant.

brandId

string

mandatory

Product brand identifier for the merchant e.g. LG, Sony etc. Should be send in the request if EMI plans are configured with brand attribute.

categoryList

string

mandatory

Product category identifiers for the merchant (categories can be Electronics, footwears etc). This should be sent in the request with same value which is configured in the EMI plan.

model

string

optional

Model id of the product. This should be sent if the merchant's EMI plans are configured with model attribute.

ean

string

optional

(Bar code Number) of product. This should be sent if the merchant's EMI plans are configured with EAN attribute.

price

double

mandatory

Cumulative price of the product (multiplied by quantity)

quantity

int

mandatory

Quantity of the product.

offerDetails

object

mandatory

OfferId that is enabled on the product

OfferDetails

Attribute	Description
offerId string mandatory	OfferId of the product

paymentDetails

object

mandatory

PaymentDetails

Attribute	Description
cardBin string optional	Starting 9 digits of credit or debit card number (Either of card number or cardBin should be send). Example: 530562100
totalTransactionAmount double mandatory	Total amount on which transaction has to be done
cardNumber string optional	Card number Example: "\|4111111111111111\|111\|012025"

generateTokenForIntent

boolean

optional

It's value can be True or False. In case, the merchant wants to start the transaction, then it's value should be sent as True, else it's value should be sent as False.

customerId

string

mandatory

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

cacheCardToken

boolean

conditional

Conditional (either of cacheCardToken or cardNumber should be present)

subventionAmount

string

optional

Amount on which merchant wants to offer subvention/Amount eligible for subvention

For Amount based only

Example: 4000.00

price

string

optional

Total amount of the cart without any subvention being applied

For Amount based only

Example: 7000.00

offerId

string

mandatory

OfferId of the product

cardTokenInfo

object

optional

Token data required to process a token transaction.

cardTokenInfo

Attribute	Description
cardToken string mandatory	16 digits Token PAN
tokenExpiry string mandatory	Token expiry. Format: MMYYYY
TAVV string mandatory	Token Verification Value generated by the network valid for a single token card payment Note: This param is not required for Diners saved card payments
cardSuffix string mandatory	Last 4 digits of the actual card.
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.
tokenUniqueReference string conditional	Token reference number is provided by the card or issuer for a given tokenization request. This param is mandatory to process Diner Card Tokens Possible Value: Any
merchantTokenRequestorId string conditional	Merchant's token requestor id provided by the Network or issuer This param is mandatory to process Diner Card Tokens Possible Value: Any
tokenType string mandatory	This parameter indicates whether the card transaction is a saved card transaction or a guest checkout transaction. Possible Values: COFT/ALTERNATE

Response Attributes

Content Type : JSON

Head

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

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. It's maximum length is 64. The different result codes corresponding to this API are mentioned below.
resultStatus string	This parameter indicates the status of API call. Possible values: S For Success , F For Failure
resultMsg string	This parameter is the result message which contains information about the result. The different result messages corresponding to this API are mentioned below in section " Response Codes and Messages".

planId

string

ID of the plan

pgPlanId

string

Identified for the EMI plan. Its value will be in the form BANK_CODE|TENUREE

emiType

enum

Type of EMI. It's value can be SUBVENTION or STANDARD.

emiLabel

string

Label for EMI [Subvention, "Zero/Low Cost EMI", Standard EMI]

rate

string

Rate of interest in percentage for this EMI charged by bank.

interval

string

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

emi

string

Effective EMI cost per month for the item.

interest

string

Interest amount for this EMI charged by bank.

gratifications

object

Gratitifications available on the plans. This field will be present for only subvention EMI plans.

Gratifications

Attribute	Description
value double	Amount of gratficication e.g. the interest amount which is to be given as discount or cashback.
type enum	Type of grattification, its value can be DISCOUNT or CASHBACK
label string	Label for gratification.

itemBreakUpList

object

Item wise breakUp of EMI and gratifications.

ItemBreakUp

Attribute

Description

string

ID of the item

interest

double

Interest aplicable on item

offerId

string

ID of the offer

amountBearer

object

EMI of the item

AmountBearer

Attribute	Description
brand double	Name of the brand (Amazon)
merchant double	Name of the merchant (MI)
platform double	Name of the platform (Paytm PG)

subventionType

enum

Type of Subvention

gratifications

object

Gratifications available on per item

Gratifications

Attribute	Description
value double	Amount of gratficication e.g. the interest amount which is to be given as discount or cashback.
type enum	Type of grattification, its value can be DISCOUNT or CASHBACK
label string	Label for gratification.

bankId

string

ID of the bank

bankName

string

Name of the bank to which card belongs.

bankCode

string

Bank code of the card (ICICI,SBI...)

cardType

string

Type of Card(CREDIT_CARD or DEBIT_CARD)

bankLogoUrl

string

URL for bank logo

emiSubventionToken

string

Token which is generated when merchant intends to do payment on the card of customer. This field is present in the response when generateTokenForIntent boolean in the request is 'True'. It will be needed to send in the initiateTransaction API request.

finalTransactionAmount

string

Amount that is returned after subvention is applied

Response Codes & Messages

resultCode	resultStatus	resultMsg
0000	S	Success
0001	F	FAILED
1001	F	Request prameters are not valid
1007	F	Missing mandatory element
2006	F	MID is invalid
EMI_001	F	Mandatory info is missing
EMI_002	F	Items's data is not valid
EMI_003	F	Items are empty
EMI_004	F	Some error occured. Please try later
EMI_005	F	Plans not available right now. Please try later
EMI_006	F	No emi options are available for these items
EMI_007	F	Invalid bank details
EMI_008	F	You are not eligible for availing EMI on this card
EMI_009	F	Selected plan does not exist
EMI_010	F	Selected plan is not eligible for these items
EMI_011	F	Selected plan details might have changed
EMI_012	F	Lock is acquired, please try after some time
EMI_013	F	Cards details are invalid
EMI_014	F	No subvented items found to be stamped
EMI_015	F	Order data could not be stamped. Please try again
EMI_016	F	Order item status could not be updated. Please try again
EMI_017	F	More than 2 retries are not allowed
EMI_018	F	EMI is not enabled on some items
EMI_019	F	Some of the selected offers are invalid
EMI_020	F	Selected plan is not offered by this bank

⇾

Staging

Production

https://securegw-stage.paytm.in/theia/api/v1/emiSubvention/validateEmi?mid={mid} copy icon

REQUEST

RESPONSE

CURL

JAVA

NODE

PHP

PYTHON

DOTNET

curl -X POST 'https://securegw-stage.paytm.in/theia/api/v1/emiSubvention/validateEmi?mid={mid}' \
--header 'Content-Type: application/json' \
--data '{"body":{"items":[{"id":"ITEMID_98765","productId":"PRODUCTID_98765","brandId":"BRANDID_98765","categoryList":["Electronics"],"quantity":"1","price":"1000","verticalId":"PAYTM_EMI","isEmiEnabled":true,"offerDetails":{"offerId":"OFFERID_98765"}}],"mid":"{mid}","customerId":"CUST_001","planId":"PLANID_98765","paymentDetails":{"totalTransactionAmount":"1000","cardBin":"411111"},"generateTokenForIntent":true},"head":{"requestId":"REQUESTID_98765","token":"{checksum}","tokenType":"CHECKSUM"}}'