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 |
---|---|---|
|
| application/json |
|
| SHA256(base64 encoded payload + '/v3/auth/authorize' + salt key) + '###' + salt index |
|
| Dynamic callback URI for server to server callback |
|
| HTTP mode to be used for server to server callback. Possible values are POST/PUT |
|
| This is checked with the deviceId passed in the /verify/otp call. |
Recommended Headers: Additional headers used for Fraud checks
Parameter Name | Mandatory | Description |
---|---|---|
|
| Manufacture of the device |
|
| Model of the Device |
|
| OS Version of device |
|
| UPI ID of user’s device |
|
| App version of the merchant |
|
| Latitude of the user’s device |
|
| Longitude of the user’s device |
|
| Network type of the device |
{
"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) |
---|---|---|---|---|
|
| Unique merchantId assigned to the merchant |
| |
|
| Provides assurance of a valid OTP verification done by the user | Mandatory for authRequestType = WALLET_AUTH |
|
|
| The type of instruments on which authorization should be allowed | Constant value = WALLET_AUTH should be passed |
|
|
| Unique TransactionID generated by the merchant |
| |
|
| Transaction amount in Paise |
| |
|
| Time after which the authorized amount is returned to the user’s usable balance. | ● Time is in minutes. |
|
|
| The message that the user will see in the transaction history page on PhonePe. |
|
{
"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 |
---|---|---|
|
| Determines the type of response object. Depends on the instrumentScope passed in the request. |
|
| Current state of the auth & capture transaction. For details, check the authState flow diagram below. |
|
| Same as Request |
|
| Same as Request |
Response codes for the edge cases where authorize fails
Code | Description |
---|---|
| Auth has already been initiated. Please check the status by calling auth status API |
| 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 |
---|---|
| Your PhonePe wallet doesn't have enough balance to fulfill your request. |
| As per RBI guidelines, please complete your KYC to use your PhonePe wallet |
| Your PhonePe wallet limit is breached. (Spend limits set by RBI have been reached) |
| Your wallet KYC state does not allow for this transaction. Please check the PhonePe app. |
Other Response Codes
Code | Description |
---|---|
| Your request has been successfully completed. |
| Invalid request payload |
| Value of X-VERIFY is incorrect |
| Something went wrong. Please call status and try again. |
| The userAuthToken provided is either expired or invalid |
| Customer is blacklisted on PhonePe side |
| Invalid user |