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

Head:

NAMEDESCRIPTIONREQUIREDEXAMPLE VALUE
clientId StringClientId by which key checksum is created, required to validate the checksum. Eg C11NoC11
version Stringapi versionNoV1
requestTimestamp StringUNIX timestamp of the time request is being sentYes1507207412152
channelId Stringrequest channelYesWEB
signature Stringchecksum valueYesCHECKSUMHASH

Body:

NAMEDESCRIPTIONREQUIRED
userToken StringPatym token issued for userConditional
totalAmount Decimalproposed transaction amount, in case of preauth it will be preauth amountYes
amountDetails Jsonamount breakup in case amount is of specific categoryNo
mid Stringmerchant identifierYes

Amount Details Object

NAMEDESCRIPTIONREQUIRED
{amount category} Decimalspecific category for which amount is to be deducted eg. "food" : 100.00ConditionalAtleast one of the amount is mandatory

Response Attributes:

API Content format: JSON

Head:

NAMEDESCRIPTIONREQUIREDEXAMPLE VALUES
clientId StringClientId by which key checksum is created, required to validate the checksum. Eg C11NoC11
version Stringapi versionNoV1
responsetimestamp Stringresponse timestampYes1507207412152
channelId Stringrequest channelYesWEB
signature Stringchecksum valueYesCHECKSUMHASH

Body:

NAMEDESCRIPTION
fundsSufficient Booleanif transaction can be done via Paytm without adding money.
addMoneyAllowed Booleanif 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 DecimalAmount that needs to be added for completing the transaction
resultInfo Jsonjson for result info

ResultInfo

NAMEDESCRIPTION
resultStatus StringStatus : SUCESS/FAILURE
resultCode StringStatus code in case of sucess/failure
resultMsg StringStatus message in case of sucess/failure

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

Response Codes and Status

CS_0000Request served successfully.
CS_0001Invalid request/ requestBody received.
CS_0002Invalid userToken received.
CS_0004Invalid amount received.
CS_0005Neither User token nor AgreementId was in the request.
AGM_0006Agreement does not exists.
AGM_0007Agreement status is invalid.
GE_0003We could not get the requested details. Please try again.
GE_0001Unknown Error
GE_1Unauthorized Access
GE_2Bad request
GE_1026We can not process your request. Please try later.
GE_1027User doesn't exist.
GE_1043Merchant does not exist
GE_1035Merchant is in inactive state.
RWL_2001You will exceed allowed debit transaction amount in wallet.

Endpoints

Staging: https://securegw-stage.paytm.in/paymentservices/pay/consult

Production: https://securegw.paytm.in/paymentservices/pay/consult

Request CodeResponse JSON

    curl -X POST 'https://securegw-stage.paytm.in/paymentservices/pay/consult' -H 'Content-Type: application/json' -d '{
        "body":{
            "userToken":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "totalAmount":"500",
            "amountDetails":{
                "food":"100.00"
            },
            "mid":"xxxxxxxxxxxxxxxxxxxx"
        },
        "head":{
            "clientId":"xxxxxxxx-xxxxxxxxxxxxx-xxxxxxx",
            "version":"V1",
            "requestTimestamp":1549889920,
            "channelId":"WEB",
            "signature":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        }}'