get https://mercury-uat.phonepe.com/v3/account/token///debit/suggest
Used before initiating a payment transaction to check the instruments available for payment, along with usable balance in the wallet.
| Header Name | Header Value |
|---|---|
Content-Type | application/json |
X-VERIFY | SHA256("/v3/account/token/{merchantId}/{userAuthToken} /debit/suggest" + saltKey) + "###" + saltIndex |
| 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 |
| 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 |
The code in the above API response could be
SUCCESSINTERNAL_SERVER_ERRORMERCHANT_USER_NOT_FOUND:INVALID_USER_AUTH_TOKEN: Token Expired. Show the linking flow to get new TokenINTERNAL_SERVER_ERROR: The server is busy or the server is not responding. Re hit the server.USER_BLACKLISTED: Customer is blacklisted on PhonePe sideUSER_BLOCKED: User is blocked for 1 day
Handling the Pay Button##Merchants need to display the message for PhonePe on the checkout page as:-
- PAY if value of debitPossible is TRUE
- Top-up & Pay if value of debitPossible is FALSE, and value of topUpPossible is TRUE
- Disable the PhonePe if value of debitPossible is FALSE, and value of topUpPossible is FALSE
Sample cases where PhonePe has to be disabled##
- KYC is not done- Please complete your wallet KYC on PhonePe
- Not in valid state - Wallet is not in the active state for topup, please visit the PhonePe app for more details
- 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