• Getting Started
    • Mobile Integration (Android/IOS)
      Enterprise Solutions
      Retail Solutions
      Accept Payments
      Process Payments
      Disbursals
      API References
      Testing
      Refunds
      Guides
      Other Processes
      Mini Program Platform

      post Fetch Instrument API

      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 Type: JSON

      Head1

      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: WEBFor websites, the value to be passed should be "WEB", WAPFor 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 parameter values by verifying the signature comes in the request. It ensures that parameter values are not tempered. Signature string can be created by using Paytm checksum library
      Body1

      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
      object 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 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"}
      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


      API Content Type: JSON

      Head2

      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
      Body2

      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 PayOptions
      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 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.
      StagingProduction
      REQUESTRESPONSE
      curl -X POST 'https://securegw-stage.paytm.in/paymentservices/fetch/instrument' \
      --header 'Content-Type: application/json' \
      --data '{"body":{"mid":"{mid}","userToken":"ae74f8b5-be5f-4503-XXXX-a60c9dcd3300"},"head":{"clientId":"C11","signature":"{signature}"}}'