Submit Auth Request

Initiates an Authorization against the wallet of a user. userAuthToken is mandatory. Auth is auto-canceled after a time period, which is configurable per merchant and can also be passed in the request.

Headers

Field NameMandatoryDescription
Content-TypeYesapplication/json
X-VerifyYesSHA256(base64 encoded payload + '/v3/auth/authorize' + salt key) + '###' + salt index
X-CALLBACK-URLNoDynamic callback URI for server to server callback
X-CALL-MODENoHTTP mode to be used for server to server callback. Possible values are POST/PUT
X-DEVICE-IDYesThis is checked with the deviceId passed in the /verify/otp call.
Note: If not passed, or fraud is suspected, the WALLET_RELINK_REQUIRED code will be returned.
Ex: 78e29dc5-872e-404a-8243-e431b25bf650bGl0bw-cWNvbQ-

Recommended Headers: Additional headers used for Fraud checks

Parameter NameMandatoryDescription
X-DEVICE-MANUFACTURERNoManufacture of the device
Ex- OnePlus
X-DEVICE-MODELNoModel of the Device
Ex- AC2001
X-OS-VERSIONNoOS Version of device
Ex- 29
X-DEVICE-UPI-IDNoUPI ID of user’s device
Ex- 431B25BF650BGL
X-MERCHANT-APP-VERSIONNoApp version of the merchant
Ex- 1.0.0
X-DEVICE-LATITUDENoLatitude of the user’s device
Ex- 39
X-DEVICE-LONGITUDENoLongitude of the user’s device
Ex- 45
X-DEVICE-NETWORK-TYPENoNetwork type of the device
Ex- MOBILE_DATA_4G
{  
   "merchantId": "MID12345",
   "userAuthToken": "U123456789",
   "transactionId": "TX123456789",
   "amount": 9900,
   "authRequestType": "WALLET_AUTH",
   "expiry": 60
}
{
"request": "eyAgCiAgICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAgInVzZXJBdXRoVG9rZW4iOiAiVTEyMzQ1Njc4OSIsCiAgICJ0cmFuc2FjdGlvbklkIjogIlRYMTIzNDU2Nzg5IiwKICAgImFtb3VudCI6IDk5MDAsCiAgICJhdXRoUmVxdWVzdFR5cGUiOiAiV0FMTEVUX0FVVEgiLAogICAiZXhwaXJ5IjogNjAKfQo="
}

Request Parameters

Field NameData TypeDescriptionCommentsMandatory (Y/N)
merchantIdStringUnique merchantId assigned to the merchantYes
userAuthTokenStringProvides assurance of a valid OTP verification done by the userMandatory for authRequestType = WALLET_AUTHConditional
authRequestTypeStringThe type of instruments on which authorization should be allowedConstant value = WALLET_AUTH should be passedYes
transactionIdStringUnique TransactionID generated by the merchantYes
amountLongTransaction amount in PaiseYes
expiryLongTime after which the authorized amount is returned to the user’s usable balance.● Time is in minutes.
● If not provided, it defaults to a preset max_default_time.
● Expiry must be less than max_default_time, else a BAD_REQUEST will be returned.
No
messageStringThe message that the user will see in the transaction history page on PhonePe.No
{
  "success": true,
  "code": "SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
      "responseType": "USER_TOKEN", 
    "amount": 9900,
    "transactionId": "TX123456789",
    "authState": "AUTHORIZED"
    }
}
{
  "success": false,
  "code": "INSUFFICIENT_BALANCE",
  "message": "Your PhonePe wallet doesn't have enough balance to fulfill your request.",
  "data": {
      "responseType": "USER_TOKEN",
      "transactionId": "TX123456789",
      "authState": "FAILED",
    }
}

Response Parameters

Field NameData TypeDescription
responseTypeStringDetermines the type of response object. Depends on the instrumentScope passed in the request.
● Will return constant value = USER_TOKEN
authStateStringCurrent state of the auth & capture transaction. For details, check the authState flow diagram below.
transactionIdStringSame as Request
amountLongSame as Request

Response codes for the edge cases where authorize fails

CodeDescription
INVALID_TRANSACTION_IDAuth has already been initiated. Please check the status by calling auth status API
WALLET_RELINK_REQUIREDFraud suspected. Please relink the PhonePe wallet on the current device.

Response codes for which which authorize failed & user can be shown a message

CodeDescription
INSUFFICIENT_BALANCEYour PhonePe wallet doesn't have enough balance to fulfill your request.
WALLET_NOT_ACTIVATEDAs per RBI guidelines, please complete your KYC to use your PhonePe wallet
WALLET_LIMIT_BREACHEDYour PhonePe wallet limit is breached. (Spend limits set by RBI have been reached)
TRANSACTION_NOT_ALLOWEDYour wallet KYC state does not allow for this transaction. Please check the PhonePe app.

Other Response Codes

CodeDescription
SUCCESSYour request has been successfully completed.
BAD_REQUESTInvalid request payload
AUTHORIZATION_FAILEDValue 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_BLACKLISTEDCustomer is blacklisted on PhonePe side
USER_DOESNOT_EXISTInvalid user
Language
Click Try It! to start a request and see the response here!