Request Headers
Header Name | Mandatory (Y/N) | Sample Value | Comments |
|---|---|---|---|
|
| 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. |
|
| application/json | |
|
| SHA256(base64 encoded payload + '/v3/wallet/debit' + salt key) + '###' + salt index | |
|
| Dynamic callback URI for server to server callback. Ideally not required as this is a sync API. | |
|
| POST | HTTP method to be used for the callback. Default to POST. |
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 |
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 | |
|---|---|---|---|---|
|
|
| Unique merchantId assigned to the merchant | |
|
|
| Unique transactionId generated by merchant. | If the responseType is not PAYMENT, the transactionId can be reused. |
|
|
| Transaction amount | |
|
|
| Identifies the OTP verified user | |
|
|
| The user’s PhonePe app version. Refer here | If debitType = TOPUP_OR_DEBIT, it is mandatory |
|
|
| Allows the merchant to choose between Top-up or Debit only functionalities. | 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 |
|---|---|---|---|
|
| Indicates which response model to deserialise into. | Will be PAYMENT |
|
| Same as Request | |
|
| PhonePe ReferenceId for an initiated Payment | |
|
| Internal payment state of the transaction. | Use the field: code to update the state of transaction in your system |
|
| The | |
|
| The | Will be null in v1 |
|
| Additional codes explaining the reason for payment failure. | This is just an informational value. |
|
| 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 |
|---|---|---|---|
|
| Indicates which response model to deserialise into. | Will be WALLET_TOPUP_DEEPLINK in v1 |
|
| Redirect Url where the user must be redirected to. |
Response codes for the edge cases where direct debit fails
Response Codes | Description |
|---|---|
| Your request was timed out. Call the transaction status API to get the transaction state |
| Something went wrong. Call the transaction status API to get the transaction state. |
| Please relink PhonePe wallet. This may occur when |
Response codes for the edge cases where redirectionUrl is returned
Response Codes | Description |
|---|---|
| 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 |
|---|---|
| As per RBI guidelines, please complete your KYC to use your PhonePe wallet |
| Transaction or top-up will exceed the user’s debit limit or credit limit |
| The current App version does not support this feature [message = link type not supported by the app. |
Other Response Codes
Code | Description |
|---|---|
| Your payment is successful |
| Payment failed |
| Invalid request payload |
| The value of X-VERIFY is incorrect |
| The userAuthToken provided is either expired or invalid |
| The customer is blacklisted on the PhonePe side |
| 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.