Get Wallet Balance

Headers

Parameter NameMandatoryDescription
X-DEVICE-IDYesTo identify the device that the user is performing the transaction on. This is checked with the device id passed in verify OTP API call
Note:
If not passed, or fraud is suspected, the
WALLET_RELINK_REQUIRED code will be returned.
Example:
78e29dc5 872e 404a 8243
e431b25bf650bGl0bw cWNvbQ
Content-TypeYesapplication/json
X-VERIFYYesSHA256(base64 encoded payload + '/v3/wallet/balance' + salt key) + '###' + salt index
X-DEVICE-MANUFACTURERNoManufacture of the device
Ex- OnePlus
X-DEVICE-MODELNoModel of the Device
Ex- AC2001
X-OS-VERSIONNoOS Version of device
Ex- 29
X-DEVICE-UPI-IDNoUPI ID of user’s device
Ex- 431B25BF650BGL
X-MERCHANT-APP-VERSIONNoApp version of the merchant
Ex- 1.0.0
X-DEVICE-LATITUDENoLatitude of the user’s device
Ex- 39
X-DEVICE-LONGITUDENoLongitude of the user’s device
Ex- 45
X-DEVICE-NETWORK-TYPENoNetwork type of the device
Ex- MOBILE_DATA_4G
{
  "merchantId": "UATMERCHANT",
  "userAuthToken": "UATMERCHANTb62c83ffdc814eb8a7d9420915e14463",
  "txnAmount": 20500,
  "topupWorkflowType": "TRANSACTIONAL",
  "deviceContext": {
      "phonePeVersionCode": 400698
    }
}
{
  "request":"ewogICJtZXJjaGFudElkIjogIlVBVE1FUkNIQU5UIiwKICAidXNlckF1dGhUb2tlbiI6ICJVQVRNRVJDSEFOVGI2MmM4M2ZmZGM4MTRlYjhhN2Q5NDIwOTE1ZTE0NDYzIiwKICAidHhuQW1vdW50IjogMjA1MDAsCiAgInRvcHVwV29ya2Zsb3dUeXBlIjogIlRSQU5TQUNUSU9OQUwiLAogICJkZXZpY2VDb250ZXh0IjogewogICAgICAicGhvbmVQZVZlcnNpb25Db2RlIjogNDAwNjk4CiAgICB9Cn0="
}

Request Parameters

Field NameData TypeMandatoryDescriptionComments
merchantIdStringYesUnique merchantId assigned to the merchant
userAuthTokenStringYesIdentifies the OTP verified user
txnAmountLongYesThe transaction amount in paise.Can be 0 for a NON_TRANSACTIONAL flow
topupWorkflowTypeEnumYesIndicates the type of journey the user is on.PossibleValues = TRANSACTIONAL, NON_TRANSACTIONAL
deviceContext.phonePeVersionCodeLongConditionalThe user’s PhonePe app version. If the App version supports top-up, topupPossible will be true. Refer hereIdeally, should always be passed. Merchants not integrating the top-up flow can skip this.
{
  "success": true,
  "code": "SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "responseType": "WALLET_ONLY",
    "wallet": {
      "availableBalance": 9900,
      "usableBalance": 9900,
      "maxTopupAllowed": 1000000,
      "debitPossible": true,
      "topupPossible": true
    },
    "displayMessage": null,
    "userIdHash": "62a496e3fcc95eff9363bf329a40495a4cbf5edaacc6c5ba6340038ac4b732e3",
    "maskedMobileNumber": null,
    "linkedUser": null
  }
}
{
    "success": true,
    "code": "SUCCESS",
    "message": "Your request has been successfully completed.",
    "data": {
        "responseType": "WALLET_ONLY",
        "wallet": {
            "availableBalance": 0,
            "usableBalance": 0,
            "maxTopupAllowed": 1000000,
            "debitPossible": false,
            "topupPossible": false
        },
        "userIdHash": "973f1575037ff9ffbdf74674e214569483779584c74cd2aa54258d5169f9d27f",
        "displayMessage": "Please complete your wallet KYC on PhonePe",
        "maskedMobileNumber": null,
        "linkedUser": null
    }
}

Response Parameters

Parameter NameData TypeDescriptionComments
responseTypeEnumDescribes the type of response object.Will be WALLET_ONLY
walletWalletObject containing wallet details
maskedMobileNumberStringObfuscated mobileNumber of the user.Not populated in v1
linkedUserBooleanIdentifies whether the user if there is a user linked with merchantUserId.Not populated in v1
userIdHashStringWill be used by the SDK to
match the user on the app.
Should be ignored by merchants.

Wallet Object Details

Field NameData TypeDescriptionComments
availableBalanceBooleanAvailable balance in PhonePe wallet
usableBalanceLongUsable balance from the
available wallet balance
taking into account the
user's KYC limits.
Use this field while
displaying balance.
maxTopupAllowedLongThe maximum top-up
amount based on the
user’s KYC limits.
debitPossibleBooleanWill be true if the user’s
wallet can be debited
with the given
txnAmount.
Checks made -
● KYC limits are not
breached and wallet
state is valid
● Balance is sufficient
topupPossibleBooleanWill be true if for the
given txnAmount -
● Top-up is
possible.
● Subsequent
debit is possible.
Checks made -
● Wallet KYC is done
● KYC limits are not
breached and wallet
state is valid (for
top-up &
subsequent debit)
● Balance is not
sufficient
● PhonePe app supports top-up

Response codes for the edge cases where wallet balance is not returned

CodeDescription
WALLET_RELINK_REQUIREDPlease relink PhonePe wallet. This may occur when-
● Fraud is suspected
● The user’s device is changed
● The user’s wallet had become inactive

Other Response Codes

CodeDescription
SUCCESSYour request has been successfully completed.
BAD_REQUESTInvalid request payload
AUTHORIZATION_FAILEDThe value of X-VERIFY is incorrect
INTERNAL_SERVER_ERRORSomething went wrong. Please call status and try again
INVALID_USER_AUTH_TOKENThe userAuthToken provided is either expired or invalid
USER_BLACKLISTEDThe customer is blacklisted on the PhonePe side
USER_DOESNOT_EXISTInvalid user

Integration Details (Wallet Balance)

Handling the Pay Button (topupWorkflowType: TRANSACTIONAL)

debitPossibletopupPossibleMessage in Button
truetruePay
truefalsePay
falsetrueTop-up & Pay
falsefalseGreyed out with message from the below table

Handling the Pay Button (topupWorkflowType: NON_TRANSACTIONAL)

debitPossibletopupPossibleMessage in Button
nulltrueTop-up
nullfalseGreyed out with message from the below table

Sample cases where a message can be shown to the user

No.CasedebitPossibletopupPossibleMessage
1KYC is not donefalsefalsePlease complete your wallet KYC on PhonePe
2Not in valid statefalsefalseWallet is not in a state for topup, please visit the PhonePe app for more details
3Debit limit/Credit
limit breached
falsefalseThe transaction will breach your wallet’s KYC limits.
Consider doing a Full KYC on PhonePe
4App version does not support top-upfalsefalseYour App version does not support wallet top-up. Please upgrade your PhonePe app

📘

Note

These messages will come as the message field in the response. There may be more of
these cases in the future, so please display these messages as they are received.

Language
Click Try It! to start a request and see the response here!