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 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

Language
Click Try It! to start a request and see the response here!