Debit is a UI based workflow to allow for Login/Registration to accept payments.
Request Headers
| Header Name | Header Value |
|---|---|
Content-Type | application/json |
X-VERIFY | SHA256(base64 encoded payload + "/v3/debit" + salt key) + ### + salt index |
X-REDIRECT-URL | Dynamic redirect URI for UI callback |
X-REDIRECT-MODE | HTTP mode to be used for UI callback |
X-CALLBACK-URL | Dynamic callback URI for server to server callback |
X-CALL-MODE | HTTP mode to be used for server to server callback |
X-PROVIDER-ID | Used for the cases where the merchant has multiple merchant IDs |
Sample Request
{
"merchantId":"UATMERCHANT",
"transactionId":"TX123456789",
"merchantUserId":"U123456789",
"amount":100,
"merchantOrderId":"OD1234",
"mobileNumber":"9xxxxxxxxx",
"message":"payment for order placed OD1234",
"subMerchantId":"DemoMerchant",
"email":"amit***[email protected]",
"shortName":"Amit"
}
{
"request": "eyAgCiAgICJtZXJjaGFudElkIjoiVUFUTUVSQ0hBTlQiLAogICAidHJhbnNhY3Rpb25JZCI6IlRYMTIzNDU2Nzg5IiwKICAgIm1lcmNoYW50VXNlcklkIjoiVTEyMzQ1Njc4OSIsCiAgICJhbW91bnQiOjEwMCwKICAgIm1lcmNoYW50T3JkZXJJZCI6Ik9EMTIzNCIsCiAgICJtb2JpbGVOdW1iZXIiOiI5eHh4eHh4eHh4IiwKICAgIm1lc3NhZ2UiOiJwYXltZW50IGZvciBvcmRlciBwbGFjZWQgT0QxMjM0IiwKICAgInN1Yk1lcmNoYW50SWQiOiJEZW1vTWVyY2hhbnQiLAogICAiZW1haWwiOiJhbWl0KioqNzVAZ21haWwuY29tIiwKICAgInNob3J0TmFtZSI6IkFtaXQiCn0="
}
Request Parameters
| Parameter Name | Type | Description | Mandatory |
|---|---|---|---|
merchantId | STRING | Unique MerchantID assigned to the merchant by PhonePe | Yes |
transactionId | STRING | Unique TransactionID generated by the merchant to track request to PhonePetransactionId length should be less than 38 characters. | Yes |
merchantUserId | STRING | Unique UserID generated by merchant. This is used to pre-login users authenticated on PhonePe. Un-authenticated users are redirected to PhonePe login page. Conversions are higher when this is provided. Avoid passing email/mobile number.Skip this for guest users. merchantUserId length should be less than 64 characters. Note: | Yes |
userAuthToken | STRING | Unique userAuthTokengiven to merchant in OTP flow. This is used to pre-login users authenticated on PhonePe. If not passed users will be redirected to PhonePe login page.Note | |
amount | LONG | Transaction amount in Paise | Yes |
merchantOrderId | STRING | OrderID generated by the merchantmerchantOrderId length should be less than 48 characters. | No |
subMerchantId | STRING | .Tag to categorize merchant transaction. Skip this field if you don't have multiple merchants tagged under one merchant id | No |
mobileNumber | STRING | Mobile number of the user | No |
message | STRING | Short message. This message is displayed to the user on completion of payment. | No |
email | STRING | Email address of the user | No |
shortName | STRING | User's name pre-filled for registration purpose. | No |
Sample Response
Found. Redirecting to /transact?token=ZTlhNGYzZmMxNDk0ZWRmYjAyNjExMWYyOWUxMjFjNGRhMjMwY2FlZWJlMjRiOWU3MjE2MGQ2MDE5NWY2YzMyMDY0ZTY4MGM3MTg1ZGJlZjJkZWNiYTE3NmRmMTA2ZTJlZTRkMmQ3YWM3OTJlOTM1YmEwMzdhNzkyOjY2NGI2MWQ2MTM4ZGZjNDk3NzNlM2JhZTE1OWI1ZDkx
Handling the Debit API Response
The HTTP Response Code will be 302.
Merchant has to check the Headers with the key "Location" which contains the token to form the PhonePe Payment redirection URL. The value of the key "Location" has to be appended with the Host URL to get the complete redirection URL.
Example for UAT:
Host URL: https://mercury-uat.phonepe.comValue of Header with Key: "Location":
/transact?token=ZTlhNGYzZmMxNDk0ZWRmYjAyNjExMWYyOWUxMjFjNGRhMjMwY2FlZWJlMjRiOWU3MjE2MGQ2MDE5NWY2YzMyMDY0ZTY4MGM3MTg1ZGJlZjJkZWNiYTE3NmRmMTA2ZTJlZTRkMmQ3YWM3OTJlOTM1YmEwMzdhNzkyOjY2NGI2MWQ2MTM4ZGZjNDk3NzNlM2JhZTE1OWI1ZDkxThe Complete Redirection URL will be:
https://mercury-uat.phonepe.com/transact?token=ZTlhNGYzZmMxNDk0ZWRmYjAyNjExMWYyOWUxMjFjNGRhMjMwY2FlZWJlMjRiOWU3MjE2MGQ2MDE5NWY2YzMyMDY0ZTY4MGM3MTg1ZGJlZjJkZWNiYTE3NmRmMTA2ZTJlZTRkMmQ3YWM3OTJlOTM1YmEwMzdhNzkyOjY2NGI2MWQ2MTM4ZGZjNDk3NzNlM2JhZTE1OWI1ZDkx
Response Parameters
| Parameter Name | Type | Description |
|---|---|---|
success | Boolean | Success status of the request |
code | Enum | See list of response codes below |
shortName | String | Short message about code |
Debit API Response Codes
Regular Debit Response Codes
| Code | Description |
|---|---|
INVALID_TRANSACTION_ID | Duplicate TransactionID |
INVALID_USER_AUTH_TOKEN | The userAuthToken provided is either invalid or not mapped to merchant. |
BAD_REQUEST | Invalid request payload |
AUTHORIZATION_FAILED | Incorrect X-VERIFY header |
INTERNAL_SERVER_ERROR | Something went wrong |
Notes
Make sure that 'follow redirection' is disabled while calling this API.
URL obj = new URL(url);
HttpURLConnection conn = (HttpURLConnection) obj.openConnection();
HttpURLConnection.setFollowRedirects(false);
conn.setInstanceFollowRedirects(false);It's recommended to have the server-to-server callback by passing the x-callback-url header.
Once the transaction is complete, user will be redirected back to the merchant.