Get Wallet Balance

Used before initiating a payment transaction to check the instruments available for payment, along with usable balance in the wallet.

Request Headers

Header NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256("/v3/account/token/{merchantId}/{userAuthToken}
/debit/suggest" + saltKey) + "###" + saltIndex

Path Parameters

Parameter NameTypeDescriptionMandatory
merchantIdStringUnique Merchant ID assigned to the merchant by PhonePeYes
userAuthTokenStringUnique userAuthToken given to merchant in OTP flow. This field is mandatory to get the user’s balance and available instruments.
Note
Yes
txnAmountLongThe transaction amount in paise.
If not passed, please make the checks in the Integration Details below
Yes

Response Parameters

Parameter NameTypeDescription
successBooleanSuccess status of the request
codeStringRefer to Response Code below for list of codes
messageStringShort message about status
responseTypeEnumDescribes the type of response object. EX- WALLET_ONLY
walletWallet JSON ObjectObject 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
userIdHashStringUsed by the SDK to match the user on the app. Should be ignored by merchants on SDKless flow.
responseCodeStringResponse Code for wallet information

WALLET JSON OBJECT

Parameter NameTypeDescription
availableBalanceLongAvailable balance in PhonePe wallet
usableBalanceLongUsable balance from PhonePe wallet
debitPossibleBooleanUsable balance from the available wallet balance considering the user's KYC limits
maxTopupAllowedLongThe maximum top-up amount based on the user’s KYC limits
topupPossibleBooleanWill be true if for the given txnAmount -
• Top-up is possible.
• Subsequent debit is possible

Response Codes

The code in the above API response could be

  • SUCCESS
  • INTERNAL_SERVER_ERROR
  • MERCHANT_USER_NOT_FOUND :
  • INVALID_USER_AUTH_TOKEN : Token Expired. Show the linking flow to get new Token
  • INTERNAL_SERVER_ERROR : The server is busy or the server is not responding. Re hit the server.
  • USER_BLACKLISTED : Customer is blacklisted on PhonePe side
  • USER_BLOCKED : User is blocked for 1 day

🚧

Handling the Pay Button##

Merchants need to display the message for PhonePe on the checkout page as:-

  1. PAY if value of debitPossible is TRUE
  2. Top-up & Pay if value of debitPossible is FALSE, and value of topUpPossible is TRUE
  3. Disable the PhonePe if value of debitPossible is FALSE, and value of topUpPossible is FALSE

Sample cases where PhonePe has to be disabled##

  1. KYC is not done- Please complete your wallet KYC on PhonePe
  2. Not in valid state - Wallet is not in the active state for topup, please visit the PhonePe app for more details
  3. Debit limit/Credit limit breached- The transaction will breach your wallet’s KYC limits. Consider doing a Full KYC on PhonePe

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!