Fetch Payment Option API

Checksum required: No

Use Case


  • To fetch payment options available for the transaction
  • To fetch payment options with which addition of fund is possible into customer’s Paytm wallet
  • To fetch saved cards of a customer. Along with saved cards, you also get a low success rate indicator. In case this indicator is positive, the customer should not be allowed to use the card
  • To fetch balance available in customer Paytm wallet and Paytm payments bank. Balance is only fetched, if the customer has logged into Paytm using Send and validate OTP flow with the same transaction token as being passed in this API request
  • To fetch list of top 5 netbanking options

Request Attributes:

API Content format: JSON

Head

PARAMETERDESCRIPTIONMANDATORY
Version String (4)Version of the API. Current version is v1Yes
requestTimestamp String (15)UNIX timestamp of the time request is being sentNo
channelId String (3)For websites, the value is WEB.
For Mobile websites/App, the value is WAP.
Yes
txnToken String (64)Provided in response of Create Subscription/ Initiate Transaction APIYes

Response Attributes:

API Content format: JSON

Head

PARAMETERDESCRIPTIONMANDATORY
Version String (2)Version of the API passed in the requestYes
responseTimestamp String (15)UNIX Timestamp of the responseYes

Body

PARAMETERDESCRIPTIONMANDATORY
paymentFlow String (12)Define the payment flow applied on merchant. Possible values (“ADDANDPAY”/“NONE”) For Subscription, this will be NONEYes
merchantPayOption PayOptionContain the payment modes that are available on merchant. Additionally consists of list of saved cards saved against the customerYes
addMoneyPayOption PayOptionContain the payOption object that are applicable for add money transaction. This will be applicable if the wallet balance is insufficient.Yes
merchantDetails MerchantDetailsDetails of the merchantYes
addMoneyMerchantDetails MerchantDetailsDetails of the merchant for add moneyNo
merchantOfferMessage StringOffer Message specific to the merchantYes
nativeJsonRequestSupported booleanJSON API request supported for custom checkout or notYes
promoCodeData PromoCodeDataData releated to promoYes
resultInfo ResultInfoResult info of the API requestYes
extraParamsMap Map <String, Object>Map for any extra informationNo
promoCode StringIt is the code that has been applied during the transaction on the merchant websiteNo

PayOption

PARAMETERDESCRIPTIONMANDATORY
paymentModes PayMethod arrayArray of different payment ModesNo
savedInstruments PayChannelBase arrayArray of saved card and other user saved instrumentsNo

PayMethod

PARAMETERDESCRIPTIONMANDATORY
displayName StringPayment Mode name like credit card/ debit cardYes
isDisabled StatusInfoflag which tells if paymethod is enabled or disabledNo
payChannelOptions PayChannelBase arrayPayment Mode Channel arrayNo
paymentMode StringPayment mode code like CREDIT_CARD/DEBIT_CARDYes

Payment Modes

PARAMETERDESCRIPTIONMANDATORY
paymentMode String (15)Payment mode codes ex- CREDIT_CARD, DEBIT_CARD, BALANCE, PPBL.Note that these codes should not be used as display namesYes
displayName String (15)Payment Modes’ name ex- credit card, debit card, Paytm Balance, Paytm Payments Bank. Note that these names should be used as display namesYes
isDisabledStatusInfoProvides the status of payment mode/instrument. If marked disabled, it is not available for the transactionYes
payChannelOptions PayChannelBase arraySuccess Rate, balance Information and issuing bank icon URL for issuing bank of Payment method.In case of NB, this will give list of top 5 used netbanks. Additionally here bank logos are also provided which can be rendered by the merchant on his cashier pageYes
isHybridDisabled booleanFlag denoting if hybrid payment is allowed with the payment modeYes
sortOrder integerOrder in which the payment mode should be displayedYes

MerchantDetails

PARAMETERDESCRIPTIONMANDATORY
mcc Stringmcc of the merchantNo
merchantVpa StringVirtual payment address of the merchantNo
merchantName StringName of the merchantNo

savedInstruments Json Object

PARAMETERDESCRIPTIONMANDATORY
issuingBank String saved instrument issuing bankYes
cardDetailsCardDetailsCard details objectYes
authModes ENUM (otp,atm) Available Authmode list for saved instrumentYes
isEmiAvailable Boolean Indicates EMI available or notYes
displayName Stringdisplay title of the saved instrumentYes
channelCode NumericChannel code of saved instrument Like Visa/MasterYes
channelName NumericChannel name of saved instrumentYes
iconUrl NumericIcon of issuing bank of saved instrumentYes
isDisabled StatusInfoProvides the status of payment mode/instrument. If marked disabled, it is not available for the transactionYes
hasLowSuccessStatusInfoIdentifier to depict low success rate on the payment mode/instrument in past 15 minutes. If the success rate is low, user should be communicated the same on the cashier page and motivated to choose a different payment instrumentYes
isHybridDisabled booleanFlag denoting if hybrid payment is allowed with the saved instrumentYes

CardDetails

PARAMETERDESCRIPTIONREQUIRED
cardId StringPaytm saved card Id unique for each cardYes
cardType ENUM (DEBIT_CARD, CREDIT_CARD)Define that merchant can accept payment from this payment modeYes
expiryDate Date (YYYYMM)Expiry date of the card YYYYMMYes
firstSixDigit StringFirst six digit of cardsYes
lastFourDigit StringLast four digit of cardsYes
status StringCard status if 1 then card is active if 0 card is inactiveYes
cvvLength Stringlength of Cvv with the cardYes
cvvRequired booleanflag to state that cvv is required or notYes

isDisabled/hasLowSuccess Json Object

PARAMETERDESCRIPTIONREQUIRED
userAccountExist BooleanDefine that user account exist for this payment modeNo
merchantAccept BooleanDefine that merchant can accept payment from this payment modeNo
Status BooleanDisable status of payment mode or instrumentYes
Msg StringDisable status messageYes

PayChannel Json Object

PARAMETERDESCRIPTIONMANDATORY
channelCode StringChannel code ex- HDFC for NB paymodeNo
channelName StringChannel name ex- HDFC bank LimitedNo
iconUrl URLIcon URL of the channelYes
isDisabled StatusInfoProvides the status of payment mode/instrument. If marked disabled, it is not available for the transactionYes
hasLowSuccess StatusInfoIdentifier to depict low success rate on the payment mode/instrument in past 15 minutes. If the success rate is low, user should be communicated the same on the cashier page and motivated to choose a different payment instrumentYes
balanceInfo BalanceInfoUser available balance information for the channel only for BALANCE payment mode. In case balance is sufficient then only wallet can be used to process transactionNo
sortOrder integerSort order of the channelNo

BalanceInfo

PARAMETERDESCRIPTIONMANDATORY
Value floatTransaction value upto 2 decimal places like 100.50Yes
Currency StringCurrency code (INR)Yes

hasLowSuccess Json object

PARAMETERDESCRIPTIONMANDATORY
Status BooleanIf success rate is lower in last 15 minutes, then the value is returned as trueYes
Msg StringMessage to display the user about the low success rateYes

ResultInfo

PARAMETERDESCRIPTIONMANDATORY
resultStatusString (S(Success), F(Failure), U(Unknown))Status of API callYes
resultCodestringResult code returned to merchant . Max length of result code can be 64Yes
resultMsgstring (Max length can be 256])Result Message contains information about the result.Yes

StatusInfo

PARAMETERDESCRIPTIONMANDATORY
status StringDisable status of payment modeYes
msg StringDisable status messageNo

PayChannelBase

PARAMETERDESCRIPTIONMANDATORY
isDisabled StatusInfoisDisabledNo
hasLowSuccess StatusInfopay channel success rateNo
iconUrl Stringicon urlYes

PromoCodeData

PARAMETERDESCRIPTIONMANDATORY
promoCodeMsg StringMessage related to the promotional CodeYes
promoCodeTypeName StringType of promo codeYes
promoCodeValid; booleanis the promo code valid for the transactionYes
promoMsg Stringmessage related to the promotional CodeYes
promoCode StringPromo code that has been applied on the transactionYes

PayMethod possible values

WALLET
PPBL
PAYTM_DIGITAL_CREDIT
UPI
EMI
DEBIT_CARD
CREDIT_CARD
NET_BANKING

Fetch Payment Options Response Codes and Description

PARAMETERDESCRIPTION
400Invalid Id supplied
00000900System error
0000Success
3001Exception in Payment RequestProcessing

Endpoints

Staging: https://securegw-stage.paytm.in/fetchPaymentOptions?mid=<mid>&orderId=<orderId>

Production: https://securegw.paytm.in/fetchPaymentOptions?mid=<mid>&orderId=<orderId>

Request CodeResponse JSON
curl -X POST 'https://securegw-stage.paytm.in/fetchPaymentOptions?mid=xxxxxxxxxxxxxxxxxxxx&orderId=xxxxxxxxxxxxxxxxxxxx' --header 'Content-Type: application/json' --data '{"head":{"version":"v1","requestTimestamp":xxxxxxxxxx,"channelId":"XXX","txnToken":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}}'