search

POSTCheck Balance API

Use Case

This API is used to consult whether the user has sufficient balance in any of the 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

Content Type : JSON

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.
Example: 1588402269

channelId
string(3)
mandatory

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"
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
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 pre-auth it will be pre-auth amount

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

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

channelId
string(3)

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"
signature
string(108)

You should validate the parameter values by verifying the signature comes in the response. It ensures that parameter values not tempered. Signature string can be verified by using Paytm checksum library.

Note: Create the signature using the body parameter of the request.

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 a 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 & Messages

resultCoderesultStatusresultMsg
CS_0000 SUCCESS Request served successfully.
CS_0001 FAILURE Invalid request/ requestBody received.
CS_0002 FAILURE Invalid userToken received.
CS_0004 FAILURE Invalid amount received.
CS_0005 FAILURE Neither User token nor AgreementId was in the request.
AGM_0006 FAILURE Agreement does not exists.
AGM_0007 FAILURE Agreement status is invalid.
GE_0003 FAILURE We could not get the requested details. Please try again.
GE_0001FAILURE Unknown Error
GE_1 FAILURE Unauthorized Access
GE_2 FAILURE Bad request
GE_1026 FAILURE We can not process your request. Please try later.
GE_1027 FAILURE User doesn't exist.
GE_1043 FAILUREMerchant does not exist
GE_1035 FAILURE Merchant is in inactive state.
RWL_2001FAILURE You will exceed allowed debit transaction amount in wallet.
RU_1000FAILUREPaytm wallet option is not available. Please visit Paytm app wallet section
403FAILUREUnauthorized Access
408FAILURETimed out from Oauth End

 

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"
                }
    }
}
⇾
Staging
Production
https://securegw-stage.paytm.in/paymentservices/pay/consultcopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/paymentservices/pay/consult' \
--header 'Content-Type: application/json' \
--data '{"body":{"userToken":"eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..xxxxxxxxxxx.9iHTtWbCZ0I6qbn2sUnyz5siw1fqbmtEnFMFE7nSIX-yrwCkiGfAC6QmPr9q-tw8LMPOh5-3UXRbpeVZEupQd3wNyaArWybRX2HAxJDRD8mxJ_wxzJM6GZ1ov4O3EIsx2Y_Zr0aHCd3VbnTjRUnlVdxXJPFG8QZs0b_2TVdoAX3_QjZS8_dwcmIWoH8ebDzOIs7MJacETfMtyFGAo8Xc0LjznToUWvTsTbIXQoF1yB0.1fZFAYJVsY61BTv2htLcXQ8800","totalAmount":"1.00","mid":"{mid}"},"head":{"clientId":"C11","signature":"{signature}"}}'
copy icon