post https://mercury-uat.phonepe.com/v3/wallet/debit
Request Headers
| Header Name | Mandatory (Y/N) | Sample Value | Comments |
|---|---|---|---|
X-DEVICE-ID | Yes | 78e29dc5-872e-404a-8243-e431b25bf650bGl0bw-cWNvbQ- | To identify the device that the user is performing the transaction on. This is checked with the deviceId passed in the /verify/otp call. Used to prevent wallet frauds. Note: If not passed, the WALLET_RELINK_REQUIRED code will be returned. |
Content-Type | Yes | application/json | |
X-VERIFY | Yes | SHA256(base64 encoded payload + '/v3/wallet/debit' + salt key) + '###' + salt index | |
X-CALLBACK-URL | No | https://webhook.site/3154f313-c2da-41fa-a926-aca993071817 | Dynamic callback URI for server to server callback. Ideally not required as this is a sync API. |
X-CALL-MODE | No | POST | HTTP method to be used for the callback. Default to POST. |
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 |
Sample Request Payload (Debit only)
{
"merchantId": "MERCHANT",
"transactionId": "TXN_113",
"amount": 5000,
"userAuthToken": "MERCHANT4ee978dbc62a4dfa8c2859b9cdb3fcee",
"debitType": "DEBIT"
}
{
"request":"ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UIiwKICAidHJhbnNhY3Rpb25JZCI6ICJUWE5fMTEzIiwKICAiYW1vdW50IjogNTAwMCwKICAidXNlckF1dGhUb2tlbiI6ICJNRVJDSEFOVDRlZTk3OGRiYzYyYTRkZmE4YzI4NTliOWNkYjNmY2VlIiwKICAiZGViaXRUeXBlIjogIkRFQklUIgp9"
}
Sample Request Payload (Top-up if balance is not sufficient)
{
"merchantId": "MERCHANT",
"transactionId": "TXN_113",
"amount": 5000,
"userAuthToken": "MERCHANT4ee978dbc62a4dfa8c2859b9cdb3fcee",
"debitType": "TOPUP_OR_DEBIT",
"deviceContext": {
"phonePeVersionCode": 400698
}
}
{
"request":"eyAgCiAgICJtZXJjaGFudElkIjogIk1FUkNIQU5UIiwKICAgInRyYW5zYWN0aW9uSWQiOiAiVFhOXzExMyIsCiAgICJhbW91bnQiOiA1MDAwLAogICAidXNlckF1dGhUb2tlbiI6ICJNRVJDSEFOVDRlZTk3OGRiYzYyYTRkZmE4YzI4NTliOWNkYjNmY2VlIiwKICAgImRlYml0VHlwZSI6ICJUT1BVUF9PUl9ERUJJVCIsCiAgICJkZXZpY2VDb250ZXh0IjogewogICAgICAgInBob25lUGVWZXJzaW9uQ29kZSI6IDQwMDY5OAogICB9Cn0="
}
Request Parameters
| Field Name | Data Type | Mandatory | Description | |
|---|---|---|---|---|
merchantId | String | Yes | Unique merchantId assigned to the merchant | |
transactionId | String | Yes | Unique transactionId generated by merchant. | If the responseType is not PAYMENT, the transactionId can be reused. |
amount | Long | Yes | Transaction amount | |
userAuthToken | String | Yes | Identifies the OTP verified user | |
deviceContext.phonePeVersionCod | Long | C | The user’s PhonePe app version. Refer here | If debitType = TOPUP_OR_DEBIT, it is mandatory |
debitType | Enum | Yes | Allows the merchant to choose between Top-up or Debit only functionalities. Pass DEBIT, if you do not want to support top-up. | Possible Values = [TOPUP_OR_DEBIT, DEBIT] |
{
"success": true,
"code": "PAYMENT_SUCCESS",
"message": "Your payment is successful.",
"data": {
"responseType": "PAYMENT",
"transactionId": "TXN_113",
"amount": 100,
"paidAmount": null,
"paymentState": "SUCCESS",
"providerReferenceId": "P2011251455161819201985",
"payResponseCode": "SUCCESS",
}
}
{
"code": "SUCCESS",
"message": "Your request has been successfully completed.",
"data": {
"responseType": "WALLET_TOPUP_DEEPLINK",
"redirectUrl": "phonepe://internal?action_nav=walletTopUp&nav_data=ewogICAgImRhdGEiOiBbCiAgICAgICAgewogICAgICAgICAgICAiaXNFbmNv..."
}
}
{
"success": false,
"code": "WALLET_NOT_ACTIVATED",
"message": "As per RBI guidelines, please complete your KYC to use your PhonePe wallet",
"data": {}
}
Response Parameters
| Field Name | Data Type | Description | Comments |
|---|---|---|---|
responseType | Enum | Indicates which response model to deserialise into. | Will be PAYMENT |
transactionId | String | Same as Request | |
providerReferenceId | String | PhonePe ReferenceId for an initiated Payment | |
paymentState | String | Internal payment state of the transaction. | Use the field: code to update the state of transaction in your system |
amount | Long | The amount sent in the request | |
paidAmount | Long | The actual debited amount after instant discount. | Will be null in v1 |
payResponseCode | String | Additional codes explaining the reason for payment failure. | This is just an informational value. |
mobileNumber | String | mobileNumber of the user | Not populated in v1 |
Note
Transaction will have been registered in PhonePePhonePe’s system only when responseType is PAYMENT.
Response Fields (For Redirection)
| Field Name | Data Type | Description | Comments |
|---|---|---|---|
responseType | Enum | Indicates which response model to deserialise into. | Will be WALLET_TOPUP_DEEPLINK in v1 |
redirectUrl | String | Redirect Url where the user must be redirected to. |
Response codes for the edge cases where direct debit fails
| Response Codes | Description |
|---|---|
TIMED_OUT | Your request was timed out. Call the transaction status API to get the transaction state |
INTERNAL_SERVER_ERROR | Something went wrong. Call the transaction status API to get the transaction state. |
WALLET_RELINK_REQUIRED | Please relink PhonePe wallet. This may occur when ● Fraud is suspected ● The user’s device is changed ● The user’s wallet had become inactive |
Response codes for the edge cases where redirectionUrl is returned
| Response Codes | Description |
|---|---|
SUCCESS | Your request has been successfully completed. |
Note
Please rely on the field responseType and not on the response code to determine the type of response: Payment or Redirection.
Response codes for the edge cases where redirectionUrl is NOT returned
| Response Codes | Description |
|---|---|
WALLET_NOT_ACTIVATED | As per RBI guidelines, please complete your KYC to use your PhonePe wallet |
WALLET_LIMIT_BREACHED | Transaction or top-up will exceed the user’s debit limit or credit limit |
APP_VERSION_NOT_SUPPORTED | The current App version does not support this feature [message = link type not supported by the app. |
Other Response Codes
| Code | Description |
|---|---|
PAYMENT_SUCCESS | Your payment is successful |
PAYMENT_ERROR | Payment failed |
BAD_REQUEST | Invalid request payload |
AUTHORIZATION_FAILED | The value of X-VERIFY is incorrect |
INVALID_USER_AUTH_TOKEN | The userAuthToken provided is either expired or invalid |
USER_BLACKLISTED | The customer is blacklisted on the PhonePe side |
USER_DOESNOT_EXIST | Invalid user |
Note: After top-up, in the second /v3/wallet/debit, if the response still
contains a redirectUrl the wallet top-up was not done, either due to user
drop off or payment.