Wallet Top-up

Returns a URL where the user can top-up their wallet

Headers

Field Name

Mandatory

Description

Content-Type

Yes

application/json

X-Verify

Yes

SHA256(base64 encoded payload + '/v3/wallet/topup' + salt key) + '###' + salt index

{
  "merchantId": "MERCHANT",
  "amount": 20500,
  "recommendedAmounts": [
    30000,
    50000,
    70000
  ],
  "adjustAmount": true,
  "linkType": "WALLET_TOPUP_DEEPLINK",
  "userAuthToken": "MERCHANT41b6f3426ed941f4a9cf467911228515",
  "topupWorkflowType": "TRANSACTIONAL",
  "deviceContext": {
    "phonePeVersionCode": 400698
  }
}
{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UIiwKICAiYW1vdW50IjogMjA1MDAsCiAgInJlY29tbWVuZGVkQW1vdW50cyI6IFsKICAgIDMwMDAwLAogICAgNTAwMDAsCiAgICA3MDAwMAogIF0sCiAgImFkanVzdEFtb3VudCI6IHRydWUsCiAgImxpbmtUeXBlIjogIldBTExFVF9UT1BVUF9ERUVQTElOSyIsCiAgInVzZXJBdXRoVG9rZW4iOiAiTUVSQ0hBTlQ0MWI2ZjM0MjZlZDk0MWY0YTljZjQ2NzkxMTIyODUxNSIsCiAgInRvcHVwV29ya2Zsb3dUeXBlIjogIlRSQU5TQUNUSU9OQUwiLAogICJkZXZpY2VDb250ZXh0IjogewogICAgInBob25lUGVWZXJzaW9uQ29kZSI6IDQwMDY5OAogIH0KfQ=="
}

Request Parameters

Field Name

Data Type

Mandatory

Description

merchantId

String

Yes

Unique merchantId assigned to the merchant

amount

Long

Yes

The transaction amount in paise

recommendedAmounts

Array

No

3 recommended amounts shown to the user apart from the default amount

  • Defaults to a multiple of the amount: 1.5x, 2x, 2.5x

adjustAmount

Boolean

No

Optional value to control if default amount should be adjusted with user’s current balance

  • Defaults to true

linkType

Enum

No

Type of redirect Url to be returned.

  • Defaults to WALLET_TOPUP_DEEPLINK

userAuthToken

String

No

User identifier for matching the user on the app.

topupWorkflowType

Enum

Yes

Indicates the type of journey the user is on.

  • PossibleValues = TRANSACTIONAL, NON_TRANSACTIONAL

deviceContext.phonePeVersionCode

Long

No

The user’s PhonePe app version. Refer here

{
  "success": true,
  "code": "SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "responseType": "WALLET_TOPUP_DEEPLINK",
    "redirectUrl": "phonepe://internal?action_nav=walletTopUp&nav_data=ewogICAgImRhdGEiOiBbCiAgICAgICAgewogICAgICAgICAgICAiaXNFbmNv..."
  }
}
{
  "success": false,
  "code": "WALLET_NOT_ACTIVATED",
  "message": "As per RBI guidelines, please complete your KYC to use your PhonePe wallet",
  "data": {}
}
{
  "success": false,
  "code": "APP_VERSION_NOT_SUPPORTED",
  "message": "Current App version does not support this feature [message = link type not supported by app.]",
  "data": {}
}

Response Parameters

Field Name

Data Type

Description

responseType

Enum

Indicates which response model to deserialise into

  • Will be WALLET_TOPUP_DEEPLINK in v1

redirectUrl

String

Redirect Url where the user must be redirected to

Response codes for the edge cases where redirectionUrl is not returned

Code

Description

WALLET_NOT_ACTIVATED

As per RBI guidelines, please complete your KYC to use your PhonePe wallet

WALLET_LIMIT_BREACHED

Transaction or top-up will exceed the user’s debit limit or credit limit.

APP_VERSION_NOT_SUPPORTED

The current App version does not support this feature [message = link type not supported by the app.]

WALLET_RELINK_REQUIRED

Please relink PhonePe wallet. This may occur when-

  • 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

🚧

NOTE

To verify whether the wallet top-up was done, the merchant can perform either of the
following, depending on their use case
● Call the wallet balance API before calling the Authorize or Direct Debit API (If the use
the case is to show wallet balance to the user before debit)
● Call the Authorize or Direct Debit API directly. If top-up was not done, Deeplink will
be returned in the response.

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