post https://mercury-uat.phonepe.com/v3/wallet/balance
Headers
| Parameter Name | Mandatory | Description |
|---|---|---|
X-DEVICE-ID | Yes | To 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-Type | Yes | application/json |
X-VERIFY | Yes | SHA256(base64 encoded payload + '/v3/wallet/balance' + salt key) + '###' + salt index |
X-DEVICE-MANUFACTURER | No | Manufacture of the device Ex- OnePlus |
X-DEVICE-MODEL | No | Model of the Device Ex- AC2001 |
X-OS-VERSION | No | OS Version of device Ex- 29 |
X-DEVICE-UPI-ID | No | UPI ID of user’s device Ex- 431B25BF650BGL |
X-MERCHANT-APP-VERSION | No | App version of the merchant Ex- 1.0.0 |
X-DEVICE-LATITUDE | No | Latitude of the user’s device Ex- 39 |
X-DEVICE-LONGITUDE | No | Longitude of the user’s device Ex- 45 |
X-DEVICE-NETWORK-TYPE | No | Network type of the device Ex- MOBILE_DATA_4G |
{
"merchantId": "UATMERCHANT",
"userAuthToken": "UATMERCHANTb62c83ffdc814eb8a7d9420915e14463",
"txnAmount": 20500,
"topupWorkflowType": "TRANSACTIONAL",
"deviceContext": {
"phonePeVersionCode": 400698
}
}
{
"request":"ewogICJtZXJjaGFudElkIjogIlVBVE1FUkNIQU5UIiwKICAidXNlckF1dGhUb2tlbiI6ICJVQVRNRVJDSEFOVGI2MmM4M2ZmZGM4MTRlYjhhN2Q5NDIwOTE1ZTE0NDYzIiwKICAidHhuQW1vdW50IjogMjA1MDAsCiAgInRvcHVwV29ya2Zsb3dUeXBlIjogIlRSQU5TQUNUSU9OQUwiLAogICJkZXZpY2VDb250ZXh0IjogewogICAgICAicGhvbmVQZVZlcnNpb25Db2RlIjogNDAwNjk4CiAgICB9Cn0="
}
Request Parameters
| Field Name | Data Type | Mandatory | Description | Comments |
|---|---|---|---|---|
merchantId | String | Yes | Unique merchantId assigned to the merchant | |
userAuthToken | String | Yes | Identifies the OTP verified user | |
txnAmount | Long | Yes | The transaction amount in paise. | Can be 0 for a NON_TRANSACTIONAL flow |
topupWorkflowType | Enum | Yes | Indicates the type of journey the user is on. | PossibleValues = TRANSACTIONAL, NON_TRANSACTIONAL |
deviceContext.phonePeVersionCode | Long | Conditional | The user’s PhonePe app version. If the App version supports top-up, topupPossible will be true. Refer here | Ideally, 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 Name | Data Type | Description | Comments |
|---|---|---|---|
responseType | Enum | Describes the type of response object. | Will be WALLET_ONLY |
wallet | Wallet | 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 | Will be used by the SDK to match the user on the app. | Should be ignored by merchants. |
Wallet Object Details
| Field Name | Data Type | Description | Comments |
|---|---|---|---|
availableBalance | Boolean | Available balance in PhonePe wallet | |
usableBalance | Long | Usable balance from the available wallet balance taking into account the user's KYC limits. | Use this field while displaying balance. |
maxTopupAllowed | Long | The maximum top-up amount based on the user’s KYC limits. | |
debitPossible | Boolean | Will 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 |
topupPossible | Boolean | Will 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
| Code | Description |
|---|---|
WALLET_RELINK_REQUIRED | Please 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
| Code | Description |
|---|---|
SUCCESS | Your request has been successfully completed. |
BAD_REQUEST | Invalid request payload |
AUTHORIZATION_FAILED | The value of X-VERIFY is incorrect |
INTERNAL_SERVER_ERROR | Something went wrong. Please call status and try again |
INVALID_USER_AUTH_TOKEN | The userAuthToken provided is either expired or invalid |
USER_BLACKLISTED | The customer is blacklisted on the PhonePe side |
USER_DOESNOT_EXIST | Invalid user |
Integration Details (Wallet Balance)
Handling the Pay Button (topupWorkflowType: TRANSACTIONAL)
| debitPossible | topupPossible | Message in Button |
|---|---|---|
| true | true | Pay |
| true | false | Pay |
| false | true | Top-up & Pay |
| false | false | Greyed out with message from the below table |
Handling the Pay Button (topupWorkflowType: NON_TRANSACTIONAL)
| debitPossible | topupPossible | Message in Button |
|---|---|---|
| null | true | Top-up |
| null | false | Greyed out with message from the below table |
Sample cases where a message can be shown to the user
| No. | Case | debitPossible | topupPossible | Message |
|---|---|---|---|---|
| 1 | KYC is not done | false | false | Please complete your wallet KYC on PhonePe |
| 2 | Not in valid state | false | false | Wallet is not in a state for topup, please visit the PhonePe app for more details |
| 3 | Debit limit/Credit limit breached | false | false | The transaction will breach your wallet’s KYC limits. Consider doing a Full KYC on PhonePe |
| 4 | App version does not support top-up | false | false | Your 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.