Direct Debit

Request Headers

Header NameMandatory (Y/N)Sample ValueComments
X-DEVICE-IDYes78e29dc5-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-TypeYesapplication/json
X-VERIFYYesSHA256(base64 encoded payload + '/v3/wallet/debit' + salt key) + '###' + salt index
X-CALLBACK-URLNohttps://webhook.site/3154f313-c2da-41fa-a926-aca993071817Dynamic callback URI for server to server callback. Ideally not required as this is a sync API.
X-CALL-MODENoPOSTHTTP method to be used for the callback. Default to POST.

Recommended Headers: Additional headers used for Fraud checks

Parameter NameMandatoryDescription
X-DEVICE-MANUFACTURERNoManufacture of the device
Ex- OnePlus
X-DEVICE-MODELNoModel of the Device
Ex- AC2001
X-OS-VERSIONNoOS Version of device
Ex- 29
X-DEVICE-UPI-IDNoUPI ID of user’s device
Ex- 431B25BF650BGL
X-MERCHANT-APP-VERSIONNoApp version of the merchant
Ex- 1.0.0
X-DEVICE-LATITUDENoLatitude of the user’s device
Ex- 39
X-DEVICE-LONGITUDENoLongitude of the user’s device
Ex- 45
X-DEVICE-NETWORK-TYPENoNetwork 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 NameData TypeMandatoryDescription
merchantIdStringYesUnique merchantId assigned to the merchant
transactionIdStringYesUnique transactionId generated by merchant.If the responseType is not PAYMENT, the transactionId can be reused.
amountLongYesTransaction amount
userAuthTokenStringYesIdentifies the OTP verified user
deviceContext.phonePeVersionCodLongCThe user’s PhonePe app version. Refer hereIf debitType = TOPUP_OR_DEBIT, it is mandatory
debitTypeEnumYesAllows 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 NameData TypeDescriptionComments
responseTypeEnumIndicates which response model to deserialise into.Will be PAYMENT
transactionIdStringSame as Request
providerReferenceIdStringPhonePe ReferenceId for an initiated Payment
paymentStateStringInternal payment state of the transaction.Use the field: code to update the state of transaction in your system
amountLongThe
amount sent in the request
paidAmountLongThe
actual debited amount after instant discount.
Will be null in v1
payResponseCodeStringAdditional codes explaining the reason for payment failure.This is just an informational value.
mobileNumberStringmobileNumber of the userNot populated in v1

🚧

Note

Transaction will have been registered in PhonePePhonePe’s system only when responseType is PAYMENT.

Response Fields (For Redirection)

Field NameData TypeDescriptionComments
responseTypeEnumIndicates which response model to deserialise into.Will be WALLET_TOPUP_DEEPLINK in v1
redirectUrlStringRedirect Url where the user must be redirected to.

Response codes for the edge cases where direct debit fails

Response CodesDescription
TIMED_OUTYour request was timed out. Call the transaction status API to get the transaction state
INTERNAL_SERVER_ERRORSomething went wrong. Call the transaction status API to get the transaction state.
WALLET_RELINK_REQUIREDPlease 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 CodesDescription
SUCCESSYour 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 CodesDescription
WALLET_NOT_ACTIVATEDAs per RBI guidelines, please complete your KYC to use your PhonePe wallet
WALLET_LIMIT_BREACHEDTransaction or top-up will exceed the user’s debit limit or credit limit
APP_VERSION_NOT_SUPPORTEDThe current App version does not support this feature [message = link type not supported by the app.

Other Response Codes

CodeDescription
PAYMENT_SUCCESSYour payment is successful
PAYMENT_ERRORPayment failed
BAD_REQUESTInvalid request payload
AUTHORIZATION_FAILEDThe value of X-VERIFY is incorrect
INVALID_USER_AUTH_TOKENThe userAuthToken provided is either expired or invalid
USER_BLACKLISTEDThe customer is blacklisted on the PhonePe side
USER_DOESNOT_EXISTInvalid 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!