post https://mercury-uat.phonepe.com/v3/auth/authorize
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 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 |