Wallet Top-up

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.