App Invoke API Parameters

Name

Request

/Response

API

Description

callbackPkg

Request(Mandatory)

All APIs (NCMC only)

Package name of the calling application. This is used for creating intent for sending the API result.

callbackDl

Request(Mandatory)

All APIs (NCMC only)

This is used for creating uri when passing API result back to the calling application , it should be valid and of the form “scheme://host”, it should be different for different API.

callbackAction

Request(Mandatory)

All APIs (NCMC only)

This action should uniquely identify your 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 of 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
Update 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

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

CARD_UPDATE_ERROR  = -13

CARD_BLOCK_NUMBER_RANGE_ERROR = -14

INCORRECT_CARD_DATA_PASSED = -15

CARD_AUTHENTICATION_ERROR = -16

SOME_BLOCK_WRITE_ERROR = -17

SOME_BLOCK_READ_ERROR = -18

CARD_BLOCK_NUMBER_READ_ERROR = -19

CARD_BLOCK_NUMBER_WRITE_ERROR = -20

TRAILER_BLOCK_NOT_ALLOWED_WRITING  =  -213

OTHERS = -1

errorMsg

Response

All APIs

Error Message, returned either by the Paytm server, or by 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.

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 maximum 96 byte for CSA update.

To Write a closed loop card, This param is to be used to write the block values in closed loop card eg: "12345678" and you can pass multiple block write values with comma separated as per the requested block numbers. eg: "12345678,87655432". Length must be maximum 16 byte to write the block number in closed loop card

ADD MONEY, BALANCE UPDATE, CHECK BALANCE

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

Card Balance in response of 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-(1)- If featureType=1 with amount=0 is passed, it will be handled as featureType=2.

Note-(2)- Kindly refer to CDAC Docs for validation elements being updated for each use-case. 

Request(Mandatory)

ADD MONEY

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

CASH - add money via cash

ACCOUNT - add money using the linked account.

It will specify an array of Tags which are required by the third party app to get card specific value. The values of all requested tags will be returned in 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

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 card

cardMfType

Request(Conditional)

READ CARD
Update 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 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 EDC device

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

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 foreground otherwise it may be killed by Android OS.

GST information parameters; all these parameters must be non-null, if GST information needs to be passed while creating 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 is separated by ':', and all the amounts are in paise format.

The date format for gstInvoiceDate param should be yyyyMMddHHmmss

Optional Parameter, the parameter should be in paisa. Tip amount should not be more than maximum allowed amount for the Merchant.

If tipAmount is present Request, then totalAmount must have to be present in the request otherwise this request will be rejected by Payments app. Sum of tipAmount field and amount field of the request must equals totalAmount field otherwise request will be rejected.

Mandatory Parameter Only For Read / Write Closed Loop Card Feature
To fetch the card block number data, merchant needs to pass which block no value he/she required, eg: "1" and now we can pass the multiple card block number with comma separated, eg: "1,2,4"
Note : The valid input block number range is  0 to 127 But it is subject to the block number that is present in a physical card. Sector trailer block is typically the last block of a sector (i.e., block 3,7 so on, in sectors 0 to 15 in a 16-block card). and it has the keys and access control permission information for the sector. 0 index block is manufacture block and it has card UUID/card no. info and not allowed to write. Currently we do not support to write the sector trailer block.

It is an optional response parameter.  It returns closed loop card block values in the same order as requested in cardBlockNumber attribute of the request parameter.
Example for Read 1 block number : "00001" , 
Example for Read N number of block number : "00001,0002" 
Example for Read N number of block number but some block failed to read :"00001,0002,ERR,00004,ERR"
ERR - stands for Error 

fBlock

If multiple blocks are present in request to Write the block value in closed loop card and some blocks are Write successfully but a few failed then it returns failed blocks with comma separated eg: "1,2". 

fBlockErrCode

If multiple blocks are present in request to Read/Write the block value in closed loop card and some blocks are Write/Read successfully but a few failed then it returns error code of failed blocks as same sequence as requested with comma separated
eg : "-16,-20". 

For read/write closed loop card block number, This param is to be used for card authentication (TYPE_A or TYPE_B) and the default value is TYPE_A.
NOTE: Except these values input other values will be ignored

For read/write closed loop card block number, This param is to be used for card authentication and the default value is FFFFFFFFFFFF. You can pass multiple values with comma separated for multiple blocks eg: FFFFFFFFFFFF,FFFFFFFFFFFF etc.
NOTE: Same number of key values should be pass in request as requested block numbers otherwise default key value will be used for the rest of block numbers

For read/write closed loop card multiple block number, If you want to use a special character other than a comma, specify it in the dataSep parameter. If dataSep is not provided or is empty, the default separator (,) will be used.
Example 1 specify the special character :
"dataSep": "|",   "blockNumbers": "1|2|3|4",   "cardData": "10809|28898|379789|47876"

Example 2 without specify the special character :
"blockNumbers": "1,2,3,4",   "cardData": "10809,28898,379789,47876"

Note: This will work only with the paymentV2 request. These values will not be printed on the receipt.

If you are using the App Invoke library, the Map<String, String> parameter allows you to:
 - Store additional transaction-related key-value pairs
 - Supports both simple key-value pairs and JSON strings
Example :
Map<String, String> extendInfo = new HashMap<>();
extendInfo.put("orderId", "12345");
extendInfo.put("splitInfo", "{"splitMethod":"PERCENTAGE","splitData":[{"vendorId":"xyz","value":"50"}]}"); //if want to pass in Percentage
extendInfo.put("splitInfo", "{"splitMethod":"AMOUNT","splitData":[{"vendorId":"abc","value":"100"}]}"); // if want to pass in amount


If you're using an Intent to pass the deeplink, you need to pass the values using the PIPE (|) operator to separate the map values.
Example : 

paytmedc://paymentV2?callbackAction=com.paytm.pos.payment.CALL_BACK_RESULT&callbackPkg=com.paytm.sdkdemo&callbackDl=sampledeeplink://payment&orderId=124566&amount=100&requestPayMode=ALL&extendInfo=param1:98765|splitInfo:"{"splitMethod":"PERCENTAGE","splitData":[{"vendorId":"xyz","value":"50"}]}"|param2:654321