Get 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-

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.

Language
Click Try It! to start a request and see the response here!