search

API Parameters

 

URL Encoding (UTF-8) is used for request and response parameters

 

Name Request
/Response
 
API Description
callbackPkg Request(Mandatory) All APIs Package name of the calling application. This is used for creating intent for sending the API result.
callbackDl Request(Mandatory) All APIs This is used for creating uri when passing API results back to the calling application, it should be valid and of the form scheme://host, it should be different for different APIs.
callbackAction Request(Mandatory) All APIs This action should uniquely identify the activity in which you want to get the API result back. If this is null, you will get the API result in your Launcher Activity.
amount Request(Mandatory)/Response(Mandatory) PAYMENT, STATUS, VOID, UPDATE CARD

For PAYMENT Request Amount is mandatory, Amount will be returned in response to STATUS and VOID request.

 

Amount 1200 means ₹12.00, last two digits are for paise.

 

For  updateCard API, the amount parameter is mandatory only for CSA (when isOsa parameter is not sent or isOsa=false is sent.)

subWalletInfo Request PAYMENT

Optional parameter for enabling users to pay through different types of Paytm wallet in case of QR payment. Make sure that the sum of amounts in this parameter is less than or equal to the total transaction amount. Two types of wallets are supported: FOOD & GIFT.

 

The parameter should be in the format "FOOD:2000|GIFT:3000" only. Amounts are in Paise.

orderId Request(Mandatory)/Response(Mandatory) All APIs OrderId must be sent in every request. OrderId can be alphanumeric and must be unique for every new payment.
flowType Request(Mandatory) READ CARD

Values: 


retail - for retail, 
transit - for NCMC, if not sent then all NCMC APIs will return Invalid Command Error, 
closed - for closed loop cards

isOsa Request/Response CREATE SERVICE, READ CARD, UPDATE CARD

Boolean to configure whether API is being used for CSA or for OSA, the default value is false.

isOsa=true :- OSA
isOsa=false :- CSA (default)

requestPayMode Request PAYMENT Request a specific PayMode to be used for Payment, Available options are CARD, QR & ALL
stackClear Request All APIs If true Intent.FLAG_ACTIVITY_CLEAR_TOP will be set while launching activity for passing result else Intent.FLAG_ACTIVITY_BROUGHT_TO_FRONT will be set.
productValidationValue Request PAYMENT Value of this parameter is used to match the Serial Number or IMEI of the selected Brand EMI product.
status Response(Mandatory) All APIs

In PAYMENT & STATUS response it contains the final status of the Payment request, while in VOID response it contains the status ,whether Void was successful or not.

Possible values in case of PAYMENT response: SUCCESS & FAIL.
Possible values in case of STATUS response: SUCCESS, FAIL & NO_TXN.
Possible values in case of VOID response: SUCCESS & FAIL.

errorCode Response All APIs

Error code, returned either by the Paytm server or by the EDC app, in case a request is not successful


EDC App Error Code -


CARD_READ_TIMEOUT = -2
PICC_READ_ERROR = -3
CARD_NOT_MATCHED = -4
ERR_TXN_DECLINED=-8
ERR_OFFLINE_DECLINED=-9
ERR_TXN_APP_BLOCKED=-10
ERR_TXN_REVERSAL_REQUIRED=-11
SERVICE_CREATION_FAILED = -101
SERVICE_ALREADY_PRESENT =-102
SERVICE_NOT_PRESENT =-103
SERVICE_SPACE_UNAVAILABLE = -104
SERVICE_DATA_INVALID_LENGTH=-111
CSA_INVALID_ERR_CODE = -112
CSA_INVALID_TXN_STATUS = -113
CSA_AMOUNT_MISMATCH=-117
CSA_INVALID_OPERATOR_ID=-114
CSA_INVALID_ACQUIRER_ID=-115
CSA_INVALID_TERMINAL_ID=-116
TRANSIT_CSA_NOT_PRESENT=942
OTHERS = -1

errorMsg Response All APIs Error Message, returned either by the Paytm server or by the EDC app, in case a request is not successful
stan Response(Mandatory) All APIs Unique transaction counter 
RRN Response PAYMENT Retrieval Reference Number returned by the bank in case of Card Payment
cardNo Response PAYMENT,
All NCMC APIs
 
Masked Card no, in case of Payment through Card.
If a Closed loop card is used, the actual serial number/UUID will be returned.
 
cardNoSHA Request(Mandatory) ADD MONEY, BALANCE UPDATE,
UPDATE CARD
Card Number, as returned by the READ CARD or CHECK BALANCE method with flowType = transit.
cardData Request(Mandatory) UPDATE CARD This is Hex String which represents data bytes that need to be sent to the card to update its Common Service Area(CSA) data for Open loop cards and card data for Closed loop cards. Length must be a maximum of 96 bytes for CSA update.
cardBalance Response ADD MONEY, BALANCE UPDATE, CHECK BALANCE

New updated Card balance after successfully executing the Add Money/Update Balance transaction.

 

Card Balance in response to Check Balance API

 

Amount 1200 means ₹12.00, last two digits are for paise.

featureType Request (Conditional) UPDATE CARD (only for CSA) 
  • featureType=0 - default, for deduction of amount != 0, no CSA element will be updated.
  • featureType=1 - for amount != 0, updating some validation elements and history.
  • featureType=2 - for amount == 0, and updating some validation elements.
  • featureType=3 - for any amount, updating some validation elements. If amount != 0, history will also be updated.
  • featureType=4 - for any amount, updating all validation elements. If amount != 0, history will also be updated.

 

Note

  • If featureType=1 with amount=0 is passed, it will be handled as featureType=2.
  • Kindly refer to CDAC Docs for validation elements being updated for each use case. 
serviceType Request(Mandatory) ADD MONEY

This is used to detect which mode is used to add money transactions.

  • CASH - Add money via cash
  • ACCOUNT - Add money using the linked account.
requestTags Request (Mandatory) READ CARD, CHECK BALANCE

It will specify an array of Tags that are required by the third-party app to get card-specific value. The values of all requested tags will be returned in an array in the same sequence in responseTags attribute in Response URL.

  • 5A - to get card number(SHA-256 for flowType = transit, otherwise SHA-512)
  • DF33 - to get Service Area Data for Open loop Cards and card Data for Closed loop cards
  • 5F25 - to get Application Effective Date
responseTags Response READ CARD, CHECK BALANCE An array of all values in same order as requested in requestTags attribute of request param. Each Tag value will be utf-8 encoded.
  • 5A - card number and salt(SHA-256 for flowType = transit, otherwise SHA-512)
  • DF33 - Common Service Area(CSA) Data for Open loop Cards and card Data for Closed loop cards
  • 5F25 - Application Effective Date in YYMMDD
txnId Response PAYMENT, 
Few NCMC APIs

Paytm Transaction Id

This will be available in these 4 NCMC APIs:- ADD MONEY,  BALANCE UPDATE, UPDATE CARD (only for CSA), CREATE SERVICE

cardType Response PAYMENT Card type CREDIT or DEBIT in case of payment through a card
cardMfType Request(Conditional) READ CARD

This parameter is for card manufacturing type. Mandatory for Closed loop cards.
 

MF - Mifare Classic, MFU - Mifare Ultralight, MFUC - Mifare Ultralight C

responsePayMode Response PAYMENT Pay mode is chosen by the user for Payment: EMI, CARD, or QR
txnDate Response PAYMENT Transaction date time
authCode Response PAYMENT Authorisation code returned by bank, null in case of QR payment
tid Response PAYMENT Terminal ID of the Paytm POS machine
aid Response PAYMENT AID used for Card Payment
payMethod Response PAYMENT Method of Payment (CREDIT_CARD, DEBIT_CARD, UPI, WALLET, etc.)
cardScheme Response PAYMENT Card company name(VISA/ MASTER)
bankResponseCode Response PAYMENT Bank Response code returned by bank
bankMid Response PAYMENT Bank MID
bankTid Response PAYMENT Bank TID
productManufacturer Response PAYMENT Brand Name of the product in case of Brand EMI SALE
productCategory Response PAYMENT In Brand EMI category of the product in case of Brand EMI SALE
productSerialNoType Response PAYMENT Validation key of the Product in case of Brand EMI SALE
productSerialNoValue Response PAYMENT Validation value of the Product in case of Brand EMI SALE
emiTxnType Response PAYMENT Type of EMI (Brand or Bank)
emiTenure Response PAYMENT Tenure of EMI
emiInterestRate Response PAYMENT Interest rate of EMI
emiMonthlyAmount Response PAYMENT Monthly amount of EMI
emiTotalAmount Response PAYMENT Total amount of EMI (with interest)
bankOfferApplied Response PAYMENT If EMI CashBack is available then true otherwise false.
bankOfferType Response PAYMENT Bank offer type of EMI
bankOfferAmount Response PAYMENT Bank offer amount of EMI
subventionCreated Response PAYMENT If EMI CashBack is available then true otherwise false.
subventionType Response PAYMENT Subvention Type in Brand EMI SALE
subventionOfferAmount Response PAYMENT EMI CashBack amount in Brand EMI
issuingBank Response PAYMENT Card issuing bank name
callbackIsService Response All APIs If this parameter is true, instead of starting an Activity with API response, we will start a Service, that Service should uniquely be identified using callbackPkg and callbackAction. If you are expecting the response in your service then your service should be exported in your manifest file, and no permission should be required to invoke your service. Also for API above and equal to Android O, your service should start in the foreground otherwise it may be killed by Android OS.
completeOrderTimeout Request (Optional) PAYMENT Timeout for automatically completing the Order (On Payment Status Page) process in seconds, it should be between 0 to 30 seconds, otherwise, it will be ignored. By default, 30 seconds.
printInfo Request PAYMENT In printInfo String, multiple parameters can be passed in the SALE request which needs to be printed on the SALE receipt
acquiringBank Response PAYMENT Name of the acquiring bank for the SALE transaction
gstIn, gstBrkUp, gstInvoiceNo, gstInvoiceDate Request PAYMENT

GST information parameters; All these parameters must be non-null if GST information needs to be passed while creating a QR code.
The gstBrkUp param must be in the form

 

"CGST:100|SGST:100|IGST:100|CESS:100|GSTIncentive:100|GSTPCT:100" where each break-up portion is separated by '|' and within each break-up portion the name and amount are separated by ':', and all the amounts are in paise format.

 

The date format for the gstInvoiceDate param should be yyyyMMddHHmmss

tipAmount Request PAYMENT Optional Parameter, the parameter should be in paisa. Tip amount should not be more than the maximum allowed amount for the Merchant.
totalAmount Request PAYMENT If tipAmount is present Request, then totalAmount must be present in the request otherwise this request will be rejected by the Payments app. Sum of tipAmount field and amount field of the request must equal totalAmount field otherwise the request will be rejected.

 

In addition to these predefined parameters merchant’s app can send any number of additional parameters in requests, and those parameters will be returned as it is in response. If the name of any additional parameter matches with predefined parameters then that additional parameter will be ignored.