Search<html-block html=”
“>
| Header Name | Header Value |
|---|---|
Content-Type | application/json |
X-VERIFY | SHA256(“/v3/account/token/{merchantId}/{userAuthToken} /debit/suggest” + saltKey) + “###” + saltIndex |
<html-block html=”
“>
| 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 |
<html-block html=”
“>
| 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 |
<html-block html=”
“>
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
{“method”:”get”,”url”:”/v3/account/token/{merchantId}/{userAuthToken}/debit/suggest”,”auth”:”never”,”apiSetting”:”5ecf9143b5bd210023b3b738″,”examples”:{“codes”:[]},”results”:{“codes”:[{“status”:200,”language”:”json”,”code”:”{\n \”success\”: true,\n \”code\”: \”SUCCESS\”,\n \”message\”: \”Your request has been successfully completed.\”,\n \”data\”: {\n \”responseType\”: \”WALLET_ONLY\”\n \”wallet\”: {\n \”availableBalance\”: 400000,\n \”usableBalance\”: 400000,\n \”maxTopupAllowed\”: \”1000000\”,\n \”debitPossible\”: \”true\”\n \”topUpPossible\”: \”true\”\n },\n “maskedMobileNumber\”: null,\n \”linkedUser\”: false,\n \”userIdHash\”: \”62a496e3fcc95eff9363bf329a40495a4cbf5edaacc6c5ba6340038ac4b732e3\”,\n }\n}”,”name”:”Success Response”},{“status”:400,”language”:”json”,”code”:”{\n \”success\”: false,\n \”code\”: \”MERCHANT_USER_NOT_FOUND\”,\n \”message\”: \”The requested user doesn”t seem to exist.\”,\n \”data\”: {\n \”merchantId\”: \”DemoMerchant\”,\n \”allowPartialPayment\”: \”no\”,\n \”upi\”: {},\n \”wallet\”: {}\n }\n}”,”name”:”Failure Response”}]},”params”:[{“name”:”merchantId”,”type”:”string”,”enumValues”:””,”default”:”M2306160483220675579140″,”desc”:”Use Unique Merchant ID assigned to the merchant by PhonePe”,”required”:false,”in”:”path”,”ref”:””,”_id”:”5a168b31f7b5a0001e036882″},{“name”:”userAuthToken”,”type”:”string”,”enumValues”:””,”default”:”M23061604832206755791408c38b65b84314a3293b8eb9a5ad43079″,”desc”:”Auth token for the user.”,”required”:false,”in”:”path”,”ref”:””,”_id”:”5a168b31f7b5a0001e036881″},{“name”:”Content-Type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”5a168b31f7b5a0001e036880″},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:”73d07ad1f4f67e33c881f724a435dccb7fdca6417fd28af609e736311911d28c###1″,”desc”:”SHA256(\”/v3/account/token/{merchantId}/{userAuthToken}/debit/suggest\” + saltKey) + \”###\” + saltIndex”,”required”:true,”in”:”header”,”ref”:””,”_id”:”5a168b31f7b5a0001e03687f”},{“name”:”txnAmount”,”type”:”long”,”enumValues”:””,”default”:”100″,”desc”:”transaction amount in paise”,”required”:false,”in”:”path”,”ref”:””,”_id”:”60bdc2fdef991e0023c2129f”},{“name”:”X-DEVICE-ID”,”type”:”string”,”enumValues”:””,”default”:”e29dc5-872e-404a-8243-e431b25bf650bGl0bw-cWNvbQ”,”desc”:”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”,”required”:true,”in”:”header”,”ref”:””,”_id”:”60bdccdd941361000f7bac13″},{“name”:”X-DEVICE-MANUFACTURER”,”type”:”string”,”enumValues”:””,”default”:”OnePlus”,”desc”:”Manufacture of the device”,”required”:false,”in”:”header”,”ref”:””,”_id”:”60bdccdd941361000f7bac12″},{“name”:”X-DEVICE-MODEL”,”type”:”string”,”enumValues”:””,”default”:”AC2001″,”desc”:”Model of the Device”,”required”:false,”in”:”header”,”ref”:””,”_id”:”60bdccdd941361000f7bac11″},{“name”:”X-OS-VERSION”,”type”:”string”,”enumValues”:””,”default”:”29″,”desc”:”OS Version of device”,”required”:false,”in”:”header”,”ref”:””,”_id”:”60bdccdd941361000f7bac10″},{“name”:”X-DEVICE-UPI-ID”,”type”:”string”,”enumValues”:””,”default”:”431B25BF650BGL”,”desc”:”UPI ID of user’s device”,”required”:false,”in”:”header”,”ref”:””,”_id”:”60bdccdd941361000f7bac0f”},{“name”:”X-MERCHANT-APP-VERSION”,”type”:”string”,”enumValues”:””,”default”:”1.0.0.1″,”desc”:”App version of the merchant”,”required”:false,”in”:”header”,”ref”:””,”_id”:”60bdccdd941361000f7bac0e”},{“name”:”X-DEVICE-LATITUDE”,”type”:”string”,”enumValues”:””,”default”:”45″,”desc”:”X-DEVICE-LONGITUDE”,”required”:false,”in”:”header”,”ref”:””,”_id”:”60bdccdd941361000f7bac0d”},{“name”:”X-DEVICE-LONGITUDE”,”type”:”string”,”enumValues”:””,”default”:”39″,”desc”:”Longitude of the user’s device”,”required”:false,”in”:”header”,”ref”:””,”_id”:”60bdccdd941361000f7bac0c”},{“name”:”X-DEVICE-NETWORK-TYPE”,”type”:”string”,”enumValues”:””,”default”:”MOBILE_DATA_4G”,”desc”:”Network type of the device”,”required”:false,”in”:”header”,”ref”:””,”_id”:”60bdccdd941361000f7bac0b”}]}
https://mercury-uat.phonepe.com