post https://mercury-uat.phonepe.com/v3/recurring/auth/init
To set up the mandate or accept the first payment from the user
Quick Links
| Subscription Flow Type | Link to Refer |
|---|---|
| Subscription - PhonePe Intent Flow | Submit Auth Request - PhonePe Intent Flow |
| Subscription - Open Intent Flow | Submit Auth Request - Open Intent Flow |
| Subscription - Collect Flow | Submit Auth Request - Collect Flow |
| Request Parameters | Submit Auth Request - Request Parameters |
| Response Parameters | Submit Auth Request - Response Parameters |
| S2S Callback | Submit Auth Request - S2S Callback |
Headers
| Field | Mandatory | Description |
|---|---|---|
Content-Type | Yes | application/json |
X-Verify | Yes | SHA256(base64 encoded payload + "/v3/recurring/auth/init" + salt key) + ### + salt index |
X-CALLBACK-URL | Yes | The callback URL to receive the server to server callback response. |
X-CALL-MODE | Yes | Value will be POST. |
Subscription - PhonePe Intent Flow
{
"merchantId": "MID12345",
"merchantUserId": "U123456789",
"subscriptionId": "OMS2006110139450123456789",
"authRequestId": "TX123456789",
"amount": 39900,
"paymentScope": "PHONEPE",
"deviceContext": {
"phonePeVersionCode": 400922
}
}
{
"merchantId": "MID12345",
"merchantUserId": "U123456789",
"subscriptionId": "OMS2006110139450123456789",
"authRequestId": "TX123456789",
"paymentScope": "PHONEPE",
"deviceContext": {
"phonePeVersionCode": 400922
}
}
{
"request":"ewogICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAibWVyY2hhbnRVc2VySWQiOiAiVTEyMzQ1Njc4OSIsCiAgInN1YnNjcmlwdGlvbklkIjogIk9NUzIwMDYxMTAxMzk0NTAxMjM0NTY3ODkiLAogICJhdXRoUmVxdWVzdElkIjogIlRYMTIzNDU2Nzg5IiwKICAiYW1vdW50IjogMzk5MDAsCiAgInBheW1lbnRTY29wZSI6ICJQSE9ORVBFIiwKICAiZGV2aWNlQ29udGV4dCI6IHsKICAgICJwaG9uZVBlVmVyc2lvbkNvZGUiOiA0MDA5MjIKICB9Cn0="
}
{
"request": "ewogICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAibWVyY2hhbnRVc2VySWQiOiAiVTEyMzQ1Njc4OSIsCiAgInN1YnNjcmlwdGlvbklkIjogIk9NUzIwMDYxMTAxMzk0NTAxMjM0NTY3ODkiLAogICJhdXRoUmVxdWVzdElkIjogIlRYMTIzNDU2Nzg5IiwKICAicGF5bWVudFNjb3BlIjogIlBIT05FUEUiLAogICJkZXZpY2VDb250ZXh0IjogewogICAgInBob25lUGVWZXJzaW9uQ29kZSI6IDQwMDkyMgogIH0KfQ=="
}
Subscription - PhonePe Intent Flow
- The value of "paymentScope" should be "PHONEPE".
- The phonePeVersionCode in "deviceContext" should be passed.
{
"success": true,
"code": "SUCCESS",
"message": "Your request has been successfully completed.",
"data": {
"redirectType": "INTENT",
"redirectURL": "ppe://mandate?pn=SUBSCRIBEMID&[email protected]&tid=YBL6663638d0312408a8f54f7df8f1bd6b9&tr=P1812191027266848105909&am=399.00&mam=399.00&cu=INR&url=https://phonepe.com&mc=7299&tn=Payment%20for%20TXN123456789&utm_source=TXN123456789&utm_medium=MID12345&utm_campaign=SUBSCRIBE_AUTH"
}
}
Subscription - Open Intent Flow
{
"merchantId": "MID12345",
"merchantUserId": "U123456789",
"subscriptionId": "OMS2006110139450123456789",
"authRequestId": "TX123456789",
"amount": 39900,
"paymentScope": "ALL_UPI_APPS",
"openIntentWithApp": "com.phonepe.app"
}
{
"merchantId": "MID12345",
"merchantUserId": "U123456789",
"subscriptionId": "OMS2006110139450123456789",
"authRequestId": "TX123456789",
"paymentScope": "ALL_UPI_APPS",
"openIntentWithApp": "com.phonepe.app"
}
{
"request": "ewogICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAibWVyY2hhbnRVc2VySWQiOiAiVTEyMzQ1Njc4OSIsCiAgInN1YnNjcmlwdGlvbklkIjogIk9NUzIwMDYxMTAxMzk0NTAxMjM0NTY3ODkiLAogICJhdXRoUmVxdWVzdElkIjogIlRYMTIzNDU2Nzg5IiwKICAiYW1vdW50IjogMzk5MDAsCiAgInBheW1lbnRTY29wZSI6ICJBTExfVVBJX0FQUFMiLAogICJvcGVuSW50ZW50V2l0aEFwcCI6ICJjb20ucGhvbmVwZS5hcHAiCn0="
}
{
"request": "ewogICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAibWVyY2hhbnRVc2VySWQiOiAiVTEyMzQ1Njc4OSIsCiAgInN1YnNjcmlwdGlvbklkIjogIk9NUzIwMDYxMTAxMzk0NTAxMjM0NTY3ODkiLAogICJhdXRoUmVxdWVzdElkIjogIlRYMTIzNDU2Nzg5IiwKICAicGF5bWVudFNjb3BlIjogIkFMTF9VUElfQVBQUyIsCiAgIm9wZW5JbnRlbnRXaXRoQXBwIjogImNvbS5waG9uZXBlLmFwcCIKfQ=="
}
Subscription - Open Intent Flow
- The value of "paymentScope" should be "ALL_UPI_APPS".
- The value of "openIntentWithApp" should be the package name of the UPI app selected for the payment.
To invoke the app-specific Intent, set the package name using setPackage() as shown below based on the app selected by the user.
Intent i = new Intent(Intent.ACTION_VIEW);
i.setData(Uri.parse(intentUrl));
i.setPackage(APP_PACKAGE_NAME);
startActivityForResult(i, PHONEPE_REQUEST_CODE);
Sample Response
{
"success": true,
"code": "SUCCESS",
"message": "Your request has been successfully completed.",
"data": {
"redirectType": "INTENT",
"redirectURL": "upi://mandate?mn=Autopay&ver=01&purpose=14&mid=SWIGGY8&am=499.00&pa=SWIGGY8%40ybl&cu=INR&mc=5812&mg=ONLINE&pn=Swiggy&Rev=Y&QRts=2022-01-17T11%3A27%3A01.168%2B05%3A30&Mode=24&QRexpire=2022-01-17T11%3A32%3A01.168%2B05%3A30&Amrule=MAX&txnType=CREATE&Validitystart=17012022&Validityend=17012023&qrMedium=00&Block=N&Share=Y&Tr=TX312131232223231234&Recur=ASPRESENTED&orgid=500044&sign=MEYCIQDjgF5nN2zh67CfJZ80/M1Tb4ElF+6QKiUoIsNSMf5X9QIhAJBDW0WPIStMzCIzLfsNM7xX1cRTUBzExBUGIPFT8RrZ"
}
}
Subscription - Collect Flow
{
"merchantId": "MID12345",
"merchantUserId": "U123456789",
"subscriptionId": "OMS2006110139450123456789",
"authRequestId": "TX123456789",
"amount": 39900,
"vpa": "[email protected]"
}
{
"merchantId": "MID12345",
"merchantUserId": "U123456789",
"subscriptionId": "OMS2006110139450123456789",
"authRequestId": "TX123456789",
"vpa": "[email protected]"
}
{
"request": "ewogICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAibWVyY2hhbnRVc2VySWQiOiAiVTEyMzQ1Njc4OSIsCiAgInN1YnNjcmlwdGlvbklkIjogIk9NUzIwMDYxMTAxMzk0NTAxMjM0NTY3ODkiLAogICJhdXRoUmVxdWVzdElkIjogIlRYMTIzNDU2Nzg5IiwKICAiYW1vdW50IjogMzk5MDAsCiAgInZwYSI6ICJhYmNAZGVmIgp9"
}
{
"request": "ewogICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAibWVyY2hhbnRVc2VySWQiOiAiVTEyMzQ1Njc4OSIsCiAgInN1YnNjcmlwdGlvbklkIjogIk9NUzIwMDYxMTAxMzk0NTAxMjM0NTY3ODkiLAogICJhdXRoUmVxdWVzdElkIjogIlRYMTIzNDU2Nzg5IiwKICAidnBhIjogImFiY0BkZWYiCn0="
}
Subscription - Collect Flow
- The value of "vpa" should be the UPI ID entered by the user.
- paymentScope parameter will be ignored if passed along with the VPA parameter.
Validate VPA
Kindly validate the VPA entered by the user using the Verify VPA API. Only if the VPA is valid then the Create Subscription API followed by Submit Auth Request API with VPA in the request payload have to be passed.
Sample Response
{
"success": true,
"code": "SUCCESS",
"message": "Your request has been successfully completed.",
"data": null
}
Request Parameters
| Field Name | Data Type | Mandatory | Description |
|---|---|---|---|
merchantId | String | Yes | MID provide by PhonePe |
merchantUserId | String | Yes | User's unique Id maintained by merchant |
subscriptionId | String | Yes | PhonePe subscription Id |
authRequestId | String | Yes | Merchant's unique transaction Id |
amount | Long | Conditional | ● Mandatory when authWorkflowType is TRANSACTION ● Do not pass when authWorkflowType is PENNY_DROP |
paymentScope | String | No | Default: PHONEPE ● PHONEPE - for PhonePe Intent ● ALL_UPI_APPS - for Open Intent |
deviceContext.phonePeVersionCode | Long | Yes(Optional) | Mandatory for SDKLess Intent flow. Refer here |
merchantContext | Context | No(Optional) | Primarily used for Offer related tags |
openIntentWithApp | String | Conditional | Mandatory if paymentScope = ALL_UPI_APPS |
vpa | String | Conditional | Mandatory for Collect based flow. |
Response Parameters
| Field Name | Data Type | Description | Comments |
|---|---|---|---|
redirectType | String | Values: ● WEB ● INTENT | The WEB redirectType is not supported in v1 |
redirectUrl | String | Based on the redirect type, url is either an intent url or web url. | The web url will not be returned in v1. |
code | String | "SUCCESS", "INTERNAL_SERVER_ERROR", "SUBSCRIPTION_NOT_FOUND", "SUBSCRIPTION_EXPIRED", "INVALID_SUBSCRIPTION_STATE", "BAD_REQUEST", "INVALID_TRANSACTION_ID" |
S2S Callback - Submit Auth Request
Callback for Submit Auth Request
The server to server callback for Submit Auth Request will have the "callbackType": "AUTH".
Validations
Validate the checksum and amount which has been passed with the response received in the Server to Server callback.
S2S Callback - ACTIVE state
{
"response": "ewogICJzdWNjZXNzIjogdHJ1ZSwKICAiY29kZSI6ICJTVUNDRVNTIiwKICAibWVzc2FnZSI6ICJZb3VyIHN1YnNjcmlwdGlvbiBpcyBhY3RpdmUuIiwKICAiZGF0YSI6IHsKICAgICJjYWxsYmFja1R5cGUiOiAiQVVUSCIsCiAgICAibWVyY2hhbnRJZCI6ICJNSUQxMjM0NSIsCiAgICAiYXV0aFJlcXVlc3RJZCI6ICJUWDEyMzQ1Njc4OSIsCiAgICAidHJhbnNhY3Rpb25EZXRhaWxzIjogewogICAgICAicHJvdmlkZXJSZWZlcmVuY2VJZCI6ICJQMTgwNjE1MTMyMzA5MzkwMDU1NDk1NyIsCiAgICAgICJhbW91bnQiOiAzOTkwMCwKICAgICAgInN0YXRlIjogIkNPTVBMRVRFRCIsCiAgICAgICJwYXlSZXNwb25zZUNvZGUiOiAiU1VDQ0VTUyIsCiAgICAgICJwYXltZW50TW9kZXMiOiBbCiAgICAgICAgewogICAgICAgICAgIm1vZGUiOiAiQUNDT1VOVCIsCiAgICAgICAgICAiYW1vdW50IjogMzk5MDAsCiAgICAgICAgICAidXRyIjogIjgxNjYyNjUyMTYxNiIKICAgICAgICB9CiAgICAgIF0KICAgIH0sCiAgICAic3Vic2NyaXB0aW9uRGV0YWlscyI6IHsKICAgICAgInN1YnNjcmlwdGlvbklkIjogIk9NUzIwMDYxMTAxMzk0NTAxMjM0NTY3ODkiLAogICAgICAic3RhdGUiOiAiQUNUSVZFIgogICAgfQogIH0KfQ=="
}
{
"success": true,
"code": "SUCCESS",
"message": "Your subscription is active.",
"data": {
"callbackType": "AUTH",
"merchantId": "MID12345",
"authRequestId": "TX123456789",
"transactionDetails": {
"providerReferenceId": "P1806151323093900554957",
"amount": 39900,
"state": "COMPLETED",
"payResponseCode": "SUCCESS",
"paymentModes": [
{
"mode": "ACCOUNT",
"amount": 39900,
"utr": "816626521616"
}
]
},
"subscriptionDetails": {
"subscriptionId": "OMS2006110139450123456789",
"state": "ACTIVE"
}
}
}
S2S Callback - FAILED state
{
"response": "ewogICJzdWNjZXNzIjogdHJ1ZSwKICAiY29kZSI6ICJTVUNDRVNTIiwKICAibWVzc2FnZSI6ICJZb3VyIHN1YnNjcmlwdGlvbiBpcyBmYWlsZWQuIiwKICAiZGF0YSI6IHsKICAgICJjYWxsYmFja1R5cGUiOiAiQVVUSCIsCiAgICAibWVyY2hhbnRJZCI6ICJNSUQxMjM0NSIsCiAgICAiYXV0aFJlcXVlc3RJZCI6ICJUWDEyMzQ1Njc4OSIsCiAgICAidHJhbnNhY3Rpb25EZXRhaWxzIjogewogICAgICAicHJvdmlkZXJSZWZlcmVuY2VJZCI6ICJQMTgwNjE1MTMyMzA5MzkwMDU1NDk1NyIsCiAgICAgICJhbW91bnQiOiAzOTkwMCwKICAgICAgInN0YXRlIjogIkZBSUxFRCIsCiAgICAgICJwYXlSZXNwb25zZUNvZGUiOiAiQVVUSE9SSVpBVElPTl9GQUlMRUQiLAogICAgICAicGF5bWVudE1vZGVzIjogWwogICAgICAgIHsKICAgICAgICAgICJtb2RlIjogIkFDQ09VTlQiLAogICAgICAgICAgImFtb3VudCI6IDM5OTAwLAogICAgICAgICAgInV0ciI6ICI4MTY2MjY1MjE2MTYiCiAgICAgICAgfQogICAgICBdCiAgICB9LAogICAgInN1YnNjcmlwdGlvbkRldGFpbHMiOiB7CiAgICAgICJzdWJzY3JpcHRpb25JZCI6ICJPTVMyMDA2MTEwMTM5NDUwMTIzNDU2Nzg5IiwKICAgICAgInN0YXRlIjogIkZBSUxFRCIKICAgIH0KICB9Cn0="
}
{
"success": true,
"code": "SUCCESS",
"message": "Your subscription is failed.",
"data": {
"callbackType": "AUTH",
"merchantId": "MID12345",
"authRequestId": "TX123456789",
"transactionDetails": {
"providerReferenceId": "P1806151323093900554957",
"amount": 39900,
"state": "FAILED",
"payResponseCode": "AUTHORIZATION_FAILED",
"paymentModes": [
{
"mode": "ACCOUNT",
"amount": 39900,
"utr": "816626521616"
}
]
},
"subscriptionDetails": {
"subscriptionId": "OMS2006110139450123456789",
"state": "FAILED"
}
}
}