Headers
Parameter Name | Mandatory | Description |
|---|---|---|
|
| 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 |
|
| application/json |
|
| SHA256(base64 encoded payload + '/v3/wallet/balance' + salt key) + '###' + salt index |
|
| Manufacture of the device |
|
| Model of the Device |
|
| OS Version of device |
|
| UPI ID of user’s device |
|
| App version of the merchant |
|
| Latitude of the user’s device |
|
| Longitude of the user’s device |
|
| Network type of the device |
{
"merchantId": "UATMERCHANT",
"userAuthToken": "UATMERCHANTb62c83ffdc814eb8a7d9420915e14463",
"txnAmount": 20500,
"topupWorkflowType": "TRANSACTIONAL",
"deviceContext": {
"phonePeVersionCode": 400698
}
}
{
"request":"ewogICJtZXJjaGFudElkIjogIlVBVE1FUkNIQU5UIiwKICAidXNlckF1dGhUb2tlbiI6ICJVQVRNRVJDSEFOVGI2MmM4M2ZmZGM4MTRlYjhhN2Q5NDIwOTE1ZTE0NDYzIiwKICAidHhuQW1vdW50IjogMjA1MDAsCiAgInRvcHVwV29ya2Zsb3dUeXBlIjogIlRSQU5TQUNUSU9OQUwiLAogICJkZXZpY2VDb250ZXh0IjogewogICAgICAicGhvbmVQZVZlcnNpb25Db2RlIjogNDAwNjk4CiAgICB9Cn0="
}
Request Parameters
Field Name | Data Type | Mandatory | Description | Comments |
|---|---|---|---|---|
|
|
| Unique merchantId assigned to the merchant | |
|
|
| Identifies the OTP verified user | |
|
|
| The transaction amount in paise. | Can be 0 for a NON_TRANSACTIONAL flow |
|
|
| Indicates the type of journey the user is on. | PossibleValues = TRANSACTIONAL, NON_TRANSACTIONAL |
|
|
| 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 |
|---|---|---|---|
|
| Describes the type of response object. | Will be WALLET_ONLY |
|
| Object containing wallet details | |
|
| Obfuscated mobileNumber of the user. | Not populated in v1 |
|
| Identifies whether the user if there is a user linked with merchantUserId. | Not populated in v1 |
|
| Will be used by the SDK to | Should be ignored by merchants. |
Wallet Object Details
Field Name | Data Type | Description | Comments |
|---|---|---|---|
|
| Available balance in PhonePe wallet | |
|
| Usable balance from the | Use this field while |
|
| The maximum top-up | |
|
| Will be true if the user’s | Checks made - |
|
| Will be true if for the | Checks made - |
Response codes for the edge cases where wallet balance is not returned
Code | Description |
|---|---|
| Please relink PhonePe wallet. This may occur when- |
Other Response Codes
Code | Description |
|---|---|
| Your request has been successfully completed. |
| Invalid request payload |
| The value of X-VERIFY is incorrect |
| Something went wrong. Please call status and try again |
| The userAuthToken provided is either expired or invalid |
| The customer is blacklisted on the PhonePe side |
| 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 | false | false | The transaction will breach your wallet’s KYC limits. |
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.