Wallet Top-up

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

Headers

Field NameMandatoryDescription
Content-TypeYesapplication/json
X-VerifyYesSHA256(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 NameData TypeMandatoryDescription
merchantIdStringYesUnique merchantId assigned to the merchant
amountLongYesThe transaction amount in paise
recommendedAmountsArrayNo3 recommended amounts shown to the user apart from the default amount
* Defaults to a multiple of the amount: 1.5x, 2x, 2.5x
adjustAmountBooleanNoOptional value to control if default amount should be adjusted with user’s current balance
* Defaults to true
linkTypeEnumNoType of redirect Url to be returned.
* Defaults to WALLET_TOPUP_DEEPLINK
userAuthTokenStringNoUser identifier for matching the user on the app.
topupWorkflowTypeEnumYesIndicates the type of journey the user is on.
* PossibleValues = TRANSACTIONAL, NON_TRANSACTIONAL
deviceContext.phonePeVersionCodeLongNoThe 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 NameData TypeDescription
responseTypeEnumIndicates which response model to deserialise into
* Will be WALLET_TOPUP_DEEPLINK in v1
redirectUrlStringRedirect Url where the user must be redirected to

Response codes for the edge cases where redirectionUrl is not returned

CodeDescription
WALLET_NOT_ACTIVATEDAs per RBI guidelines, please complete your KYC to use your PhonePe wallet
WALLET_LIMIT_BREACHEDTransaction or top-up will exceed the user’s debit limit or credit limit.
APP_VERSION_NOT_SUPPORTEDThe current App version does not support this feature [message = link type not supported by the app.]
WALLET_RELINK_REQUIREDPlease relink PhonePe wallet. This may occur when-
* The User’s wallet had become inactive

Other Response Codes

CodeDescription
SUCCESSYour request has been successfully completed.
BAD_REQUESTInvalid request payload
AUTHORIZATION_FAILEDThe value of X-VERIFY is incorrect
INTERNAL_SERVER_ERRORSomething went wrong. Please call status and try again
INVALID_USER_AUTH_TOKENThe userAuthToken provided is either expired or invalid
USER_BLACKLISTEDThe customer is blacklisted on the PhonePe side
USER_DOESNOT_EXISTInvalid 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!