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

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