Submit Auth Request

Headers

Field Name	Mandatory	Description
`Content-Type`	`Yes`	application/json
`X-Verify`	`Yes`	SHA256(base64 encoded payload + '/v3/auth/authorize' + salt key) + '###' + salt index
`X-CALLBACK-URL`	`No`	Dynamic callback URI for server to server callback
`X-CALL-MODE`	`No`	HTTP mode to be used for server to server callback. Possible values are POST/PUT
`X-DEVICE-ID`	`Yes`	This 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 Name	Mandatory	Description
`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": "MID12345",
   "userAuthToken": "U123456789",
   "transactionId": "TX123456789",
   "amount": 9900,
   "authRequestType": "WALLET_AUTH",
   "expiry": 60
}

{
"request": "eyAgCiAgICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAgInVzZXJBdXRoVG9rZW4iOiAiVTEyMzQ1Njc4OSIsCiAgICJ0cmFuc2FjdGlvbklkIjogIlRYMTIzNDU2Nzg5IiwKICAgImFtb3VudCI6IDk5MDAsCiAgICJhdXRoUmVxdWVzdFR5cGUiOiAiV0FMTEVUX0FVVEgiLAogICAiZXhwaXJ5IjogNjAKfQo="
}

Request Parameters

Field Name	Data Type	Description	Comments	Mandatory (Y/N)
`merchantId`	`String`	Unique merchantId assigned to the merchant		`Yes`
`userAuthToken`	`String`	Provides assurance of a valid OTP verification done by the user	Mandatory for authRequestType = WALLET_AUTH	`Conditional`
`authRequestType`	`String`	The type of instruments on which authorization should be allowed	Constant value = WALLET_AUTH should be passed	`Yes`
`transactionId`	`String`	Unique TransactionID generated by the merchant		`Yes`
`amount`	`Long`	Transaction amount in Paise		`Yes`
`expiry`	`Long`	Time 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`
`message`	`String`	The 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 Name	Data Type	Description
`responseType`	`String`	Determines the type of response object. Depends on the instrumentScope passed in the request. ● Will return constant value = USER_TOKEN
`authState`	`String`	Current state of the auth & capture transaction. For details, check the authState flow diagram below.
`transactionId`	`String`	Same as Request
`amount`	`Long`	Same as Request

Response codes for the edge cases where authorize fails

Code	Description
`INVALID_TRANSACTION_ID`	Auth has already been initiated. Please check the status by calling auth status API
`WALLET_RELINK_REQUIRED`	Fraud suspected. Please relink the PhonePe wallet on the current device.

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

Code	Description
`INSUFFICIENT_BALANCE`	Your PhonePe wallet doesn't have enough balance to fulfill your request.
`WALLET_NOT_ACTIVATED`	As per RBI guidelines, please complete your KYC to use your PhonePe wallet
`WALLET_LIMIT_BREACHED`	Your PhonePe wallet limit is breached. (Spend limits set by RBI have been reached)
`TRANSACTION_NOT_ALLOWED`	Your wallet KYC state does not allow for this transaction. Please check the PhonePe app.

Other Response Codes

Code	Description
`SUCCESS`	Your request has been successfully completed.
`BAD_REQUEST`	Invalid request payload
`AUTHORIZATION_FAILED`	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`	Customer is blacklisted on PhonePe side
`USER_DOESNOT_EXIST`	Invalid user