paytm developer docs logoDeveloperDocumentation
search

POSTFetch Instrument API

Use Case

This API returns all applicable instruments for the customer and merchant combination with the information about fund sufficiency for each instrument.

In case of funds are insufficient in the instrument, the deficit amount is returned along with the instrument details.

Request Attributes

Content Type : JSON

Head

AttributeDescription
version
string(4)
optional

Version of the API.

Example: v1

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"
requestTimestamp
string(15)
optional

EPOCH timestamp of the time at which request is being sent.
Example: 1588402269

clientId
string(3)
mandatory

Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key.

Example: C11

signature
string(108)
mandatory

Paytm validates the request and ensures that parameters are not tempered by verifying the signature in the request. For creating the checksum (signature) refer to the steps given in Checksum Logic.
Note: Create the signature using the body parameter of the request.

Body

AttributeDescription
userToken
string
mandatory

This is a unique token linked with user's Paytm wallet and is provided in the response while linking user's Paytm wallet.

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

txnAmount
double
optional

Txn Amount to compare with pay Option balance.
e.g. 1.00

subwalletAmount
object
optional

This parameter is required to limit the maximum amount that could be deducted from a particular subwallet. This parameter is only used for payMode PPI (Paytm Wallet).

Possible Keys: FOOD, GIFT, MULTI_PURPOSE_GIFT, TOLL, CLOSED_LOOP_WALLET, CLOSED_LOOP_SUB_WALLET, FUEL, INTERNATIONAL_FUNDS_TRANSFER, CASHBACK, GIFT_VOUCHER. e.g. "subwalletAmount":{ "FOOD": "2"}

showExpiredMerchantGVBalance
boolean
optional

This parameter is required in merchant wants to have expired Merchant GV Balance in Fetch Instrument Response.

Possible Values: TRUE, FALSE.
Note: Attribute is in development phase.

Response Attributes

Content Type : JSON

Head

AttributeDescription
clientId
string(3)

Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key.

Example: C11

version
string(2)

Version of the API passed in the request.
Example: v1

responseTimestamp
string(15)

EPOCH timestamp of the time at which response is being sent.
Example: 1588402269

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. 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: SUCCESS, FAILURE

resultMsg
string(256)

This parameter is the result message which contains information about the result.The different result messages corresponding to this API are mentioned below.
 

payOptions
object

List of payOptions that a user can pay from to a merchant.

PayOptions
+
AttributeDescription
payMethod
string

payOption Name to be pass in withdraw request

displayName
string

Display Name of PayOption

fundSufficient
boolean

Amount Sufficient in PayMethod to do the transaction. Only shown if txnAmount comes in the request.

amount
double

Total usable balance present in payOption. Always shown for payOption = GIFT_VOUCHER For other payOption , it is based on preference given to the merchant. e.g. 1.00

addMoneyAllowed
boolean

if add money can be done to that payMode to complete the transaction true in case funds are not sufficient but transaction can be completed by doing add money false otherwise. Only shown if txnAmount comes in the request.

deficitAmount
double

Amount that needs to be added to the payMode for completing the transaction.
Only shown if txnAmount comes in the request. e.g. 1.00.

expiredAmount
double

Total expired amount present in payOption Only shown for payOption = GIFT_VOUCHER if showExpiredMerchantGVBalance is true. e.g. 1.00
Note: Attribute is in development phase.

Response Codes & Messages

resultCoderesultStatusresultMsg
SUCCESS SUCCESS Request served successfully.
FI_0001 FAILURE Invalid Request.
FI_0002 FAILURE Merchant is on agreement pay.
FI_0003 FAILURE Invalid Token.
WM_1003 FAILURE Merchant does not exist.
403 FAILURE Unauthorized Access
GE_0003 FAILURE We could not get the requested details. Please try again.
GE_3 FAILURE Internal server error.
RU_1000FAILUREPaytm wallet option is not available. Please visit Paytm app wallet section
⇾
Staging
Production
https://securegw-stage.paytm.in/paymentservices/fetch/instrumentcopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/paymentservices/fetch/instrument' \
--header 'Content-Type: application/json' \
--data '{"body":{"mid":"{mid}","userToken":"eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..xxxxxxxxxxx.9iHTtWbCZ0I6qbn2sUnyz5siw1fqbmtEnFMFE7nSIX-yrwCkiGfAC6QmPr9q-tw8LMPOh5-3UXRbpeVZEupQd3wNyaArWybRX2HAxJDRD8mxJ_wxzJM6GZ1ov4O3EIsx2Y_Zr0aHCd3VbnTjRUnlVdxXJPFG8QZs0b_2TVdoAX3_QjZS8_dwcmIWoH8ebDzOIs7MJacETfMtyFGAo8Xc0LjznToUWvTsTbIXQoF1yB0.1fZFAYJVsY61BTv2htLcXQ8800"},"head":{"clientId":"C11","signature":"{signature}"}}'
copy icon