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 Name

Header Value

Content-Type

application/json

X-VERIFY

SHA256("/v3/account/token/{merchantId}/{userAuthToken}
/debit/suggest" + saltKey) + "###" + saltIndex

Path Parameters

Parameter Name

Type

Description

Mandatory

merchantId

String

Unique Merchant ID assigned to the merchant by PhonePe

Yes

userAuthToken

String

Unique userAuthToken given to merchant in OTP flow. This field is mandatory to get the user’s balance and available instruments.
Note

Yes

txnAmount

Long

The transaction amount in paise.
If not passed, please make the checks in the Integration Details below

Yes

Response Parameters

Parameter Name

Type

Description

success

Boolean

Success status of the request

code

String

Refer to Response Code below for list of codes

message

String

Short message about status

responseType

Enum

Describes the type of response object. EX- WALLET_ONLY

wallet

Wallet JSON Object

Object containing wallet details

maskedMobileNumber

String

Obfuscated mobileNumber of the user. Not populated in v1

linkedUser

Boolean

Identifies whether the user if there is a user linked with merchantUserId. Not populated in v1

userIdHash

String

Used by the SDK to match the user on the app. Should be ignored by merchants on SDKless flow.

responseCode

String

Response Code for wallet information

WALLET JSON OBJECT

Parameter Name

Type

Description

availableBalance

Long

Available balance in PhonePe wallet

usableBalance

Long

Usable balance from PhonePe wallet

debitPossible

Boolean

Usable balance from the available wallet balance considering the user's KYC limits

maxTopupAllowed

Long

The maximum top-up amount based on the user’s KYC limits

topupPossible

Boolean

Will 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!