• 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 Check Balance API

      Use Case


      This API is used to consult whether the user has sufficient balance in any of Paytm proprietary instruments. API will also provide deficit amount in case the amount is insufficient and Add Money is required to complete the transaction

      Request Attributes


      API Content Type: JSON

      Head1

      Head

      ATTRIBUTEDESCRIPTION
      clientId string(3)
      optional
      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(4)
      optional
      Version of the API.
      Example: v1
      requestTimestamp string(15)
      mandatory
      EPOCH timestamp of the time at which request is being sent.
      channelId string(3)
      mandatory
      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"
      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
      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
      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.
      totalAmount decimal
      mandatory
      proposed transaction amount, in case of preauth it will be preauth amount
      amountDetails json
      optional
      amount breakup in case amount is of specific category
      AmountDetails +
      AttributeDescription
      amount category decimal
      conditional
      specific category for which amount is to be deducted eg. "food" : 100.00

      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
      channelId string(3)
      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"
      signature string(108)
      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
      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
      fundsSufficient boolean
      if transaction can be done via Paytm without adding money.
      addMoneyAllowed boolean
      if add money can be done to complete the transaction true in case funds are not sufficient but transaction can be completed by doing add money false otherwise
      deficitAmount decimal
      Amount that needs to be added for completing the transaction

      Response Codes and Messages


      resultCoderesultStatusresultMsg
      CS_0000SUCCESSRequest served successfully.
      CS_0001FAILUREInvalid request/ requestBody received.
      CS_0002FAILUREInvalid userToken received.
      CS_0004FAILUREInvalid amount received.
      CS_0005FAILURENeither User token nor AgreementId was in the request.
      AGM_0006FAILUREAgreement does not exists.
      AGM_0007FAILUREAgreement status is invalid.
      GE_0003FAILUREWe could not get the requested details. Please try again.
      GE_0001FAILUREUnknown Error
      GE_1FAILUREUnauthorized Access
      GE_2FAILUREBad request
      GE_1026FAILUREWe can not process your request. Please try later.
      GE_1027FAILUREUser doesn't exist.
      GE_1043FAILUREMerchant does not exist
      GE_1035FAILUREMerchant is in inactive state.
      RWL_2001YFAILUREou will exceed allowed debit transaction amount in wallet.

      Sample Response

      • Sufficient balance with wallet
      {
          "head": {
                      "clientId": "C11",
                      "version": "v1",
                      "responseTimestamp": "1507207412152",
                      "signature": "<CHECKSUMHASH>"
          },
          "body": {
                      "fundsSufficient": true,
                      "addMoneyAllowed": false,
                      "deficitAmount": "0",
                      "resultInfo": {
                                  "resultCode": "00023424/234234234",
                                  "resultStatus": "Sucesss",
                                  "resultMsg": "Sucess"
                      }
          }
      }
      • Sufficient balance with Postpaid
      {
          "head": {
                      "clientId": "C11",
                      "version": "v1",
                      "responseTimestamp": "1507207412152",
                      "signature": "<CHECKSUMHASH>"
          },
          "body": {
                      "fundsSufficient": true,
                      "addMoneyAllowed": false,
                      "deficitAmount": "0",
                      "resultInfo": {
                                  "resultCode": "00023424/234234234",
                                  "resultStatus": "Sucesss",
                                  "resultMsg": "Sucess"
                      }
          }
      }
      • Insufficient balance Add Money allowed
      {
          "head": {
                      "clientId": "C11",
                      "version": "v1",
                      "responseTimestamp": "1507207412152",
                      "signature": "<CHECKSUMHASH>"
          },
          "body": {
                      "fundsSufficient": false,
                      "addMoneyRequired": true,
                      "deficitAmount": "100.00",
                      "resultInfo": {
                                  "resultCode": "00023424/234234234",
                                  "resultStatus": "Sucesss",
                                  "resultMsg": "Sucess"
                      }
          }
      }
      • Insufficient balance & Add Money not allowed
      {
          "head": {
                      "clientId": "C11",
                      "version": "v1",
                      "responseTimestamp": "1507207412152",
                      "signature": "<CHECKSUMHASH>"
          },
          "body": {
                      "fundsSufficient": false,
                      "addMoneyRequired": false,
                      "deficitAmount": "100.00",
                      "resultInfo": {
                                  "resultCode": "00023424/234234234",
                                  "resultStatus": "Success",
                                  "resultMsg": "Success"
                      }
          }
      }
      StagingProduction
      REQUESTRESPONSE
      curl -X POST 'https://securegw-stage.paytm.in/paymentservices/pay/consult' \
      --header 'Content-Type: application/json' \
      --data '{"body":{"userToken":"ae74f8b5-be5f-4503-XXXX-a60c9dcd3300","totalAmount":"1.00","mid":"{mid}"},"head":{"clientId":"C11","signature":"{signature}"}}'