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

Attribute	Description
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

Attribute

Description

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

Attribute	Description
amount category decimal conditional	specific category for which amount is to be deducted eg. "food" : 100.00

Response Attributes

Content Type : JSON

Head

Attribute	Description
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

Attribute

Description

resultInfo

object

This parameter gives the information about the result of the API response

ResultInfo

Attribute	Description
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

resultCode	resultStatus	resultMsg
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_0001	FAILURE	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	FAILURE	Merchant does not exist
GE_1035	FAILURE	Merchant is in inactive state.
RWL_2001	FAILURE	You will exceed allowed debit transaction amount in wallet.
RU_1000	FAILURE	Paytm wallet option is not available. Please visit Paytm app wallet section
403	FAILURE	Unauthorized Access
408	FAILURE	Timed 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/consult copy 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}"}}'