• Getting Started
    • Website Integration
      Mobile Integration (Android/IOS)
      Enterprise Solutions
      Accept Payments
      Process Payments
      Disbursals
      API References
      Webhooks
      Testing
      Refunds
      Guides
      Other Processes

      Fetch Instrument API

      Checksum required: Yes

      Use Case

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

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

      Request Attributes

      API Content format: JSON

      Head

      ATTRIBUTEDESCRIPTIONMANDATORY
      clientId StringClientId by which key checksum is created, required to validate the checksum. Eg C11.Yes
      version String (4)Version of the API.Current version is v1.No
      requestTimestamp String (15)UNIX timestamp of the time request is being sentNo
      channelId String (3)Channel through which call is initiated.
      For websites, the value is WEB
      For Mobile websites/App, the value is WAP.
      No
      signature StringChecksum string created by using Paytm checksum logicYes

      Body

      ATTRIBUTEDESCRIPTIONMANDATORY
      userToken StringPatym token issued for userYes
      mid StringThis is a unique identifier provided to every merchant by Paytm.Yes
      txnAmount DoubleTxn Amount to compare with pay Option balance.
      e.g. 1.00
      No
      subwalletAmount StringThis 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 include: 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"}
      No
      showExpiredMerchantGVBalance BooleanThis 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.
      No

      Response Attributes

      Head

      ATTRIBUTEDESCRIPTION
      clientId StringClientId by which key checksum is created, required to validate the checksum. Eg C11
      version String (2)Version of the API. Current version is v1.
      responseTimestamp String (15)UNIX Timestamp of the response

      Body

      ATTRIBUTEDESCRIPTION
      payOptions PayOptionsList of payOptions that a user can pay from to a merchant
      resultInfo ResultInfoInformation related to response of the request

      PayOptions

      ATTRIBUTEDESCRIPTION
      payMethod StringpayOption Name to be pass in withdraw request
      displayName StringDisplay Name of PayOption
      fundSufficient BooleanAmount Sufficient in PayMethod to do the transaction.
      Only shown if txnAmount comes in the request.
      amount DoubleTotal 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 Booleanif 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 otherwis
      Only shown if txnAmount comes in the request.
      deficitAmount DoubleAmount 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 DoubleTotal 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.

      ResultInfo

      ATTRIBUTEDESCRIPTIONMANDATORY
      resultCodeStringResult code returned to merchant . Max length of result code can be 64Yes
      resultStatusStringStatus of API call
      (S:Success, F:Failure, U:Unknown)
      Yes
      resultMsgStringResult Message contains information about the result.Yes

      Response Codes and Messages

      resultCoderesultStatusresultMsg
      SUCCESSSUCCESSRequest served successfully.
      FI_0001FAILUREInvalid Request.
      FI_0002FAILUREMerchant is on agreement pay.
      FI_0003FAILUREInvalid Token.
      WM_1003FAILUREMerchant does not exist.
      403FAILUREUnauthorized Access
      GE_0003FAILUREWe could not get the requested details. Please try again.
      GE_3FAILUREInternal server error.

      Endpoints

      Staging: https://securegw-stage.paytm.in/paymentservices/fetch/instrument

      Production: https://securegw.paytm.in/paymentservices/fetch/instrument

      Request CodeResponse JSON
      curl -X POST 'https://securegw-stage.paytm.in/paymentservices/fetch/instrument' 
                 --header 'Content-Type: application/json' 
                 --data '{"body":{"mid":"{mid}","userToken":"{user-token}"},"head":{"clientId":"C11","signature":"{signature}"}}'