post https://mercury-uat.phonepe.com/v3/recurring/debit/init
To notify in advance the user about the recurring debit. The API can also be used
to debit the amount.
Headers
| Header Name | Mandatory | Header Value |
|---|---|---|
Content-Type | Yes | application/json |
X-Verify | Yes | SHA256(base64 encoded payload + "/v3/recurring/debit/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. |
{
"merchantId": "MID12345",
"merchantUserId": "U123456789",
"subscriptionId": "OMS2006110139450123456789",
"transactionId": "TX1234567890",
"autoDebit": true,
"amount": 39900
}
{
"request":"ewogICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAibWVyY2hhbnRVc2VySWQiOiAiVTEyMzQ1Njc4OSIsCiAgInN1YnNjcmlwdGlvbklkIjogIk9NUzIwMDYxMTAxMzk0NTAxMjM0NTY3ODkiLAogICJ0cmFuc2FjdGlvbklkIjogIlRYMTIzNDU2Nzg5MCIsCiAgImF1dG9EZWJpdCI6IHRydWUsCiAgImFtb3VudCI6IDM5OTAwCn0="
}
Request Parameters
| Field Name | Data Type | Mandatory | Description | Comments |
|---|---|---|---|---|
merchantId | String | Yes | MID provided by PhonePe | |
merchantUserId | String | Yes | User's unique Id maintained by merchant | |
subscriptionId | String | Yes | PhonePe subscription Id | |
transactionId | String | Yes | Merchant's unique transaction Id | |
amount | Long | Yes | Conditionally Optional | Mandatory when subscription amountType is VARIABLE |
autoDebit | Boolean | No(Optional) | Default: false Values: true/false | When this flag is set no debit/execute would be needed or allowed |
{
"success": true,
"code": "SUCCESS",
"message": "Your request has been successfully submitted.",
"data": {
"notificationId": "OMN2006110154420123456789",
"state": "ACCEPTED",
"amount": 39900
}
}
Response Parameters
| Field Name | Data Type | Description |
|---|---|---|
notificationId | String | Merchant’s SubscriptionId |
amount | Long | Amount |
state | String | ● ACCEPTED ● FAILED |
notifiedAt | Int | Epoch time when the user is notified. |
validAfter | Int | Epoch time when the user is notified. |
validUpto | Int | Epoch time after which the user cannot be debited. |
S2S Callback - Recurring INIT
Callback for Recurring INIT
The server to server callback for Recurring INIT will have the "callbackType": "NOTIFY".
Validations
Validate the checksum and amount which has been passed with the response received in the Server to Server callback.
Sample Response
{
"response": "ewogICJzdWNjZXNzIjogdHJ1ZSwKICAiY29kZSI6ICJTVUNDRVNTIiwKICAibWVzc2FnZSI6ICJVc2VyIGRlYml0IG5vdGlmaWNhdGlvbiBpcyBzdWNjZXNzZnVsLiIsCiAgImRhdGEiOiB7CiAgICAiY2FsbGJhY2tUeXBlIjogIk5PVElGWSIsCiAgICAibWVyY2hhbnRJZCI6ICJNSUQxMjM0NSIsCiAgICAidHJhbnNhY3Rpb25JZCI6ICJUWDEyMzQ1Njc4OTAiLAogICAgIm5vdGlmaWNhdGlvbkRldGFpbHMiOiB7CiAgICAgICJub3RpZmljYXRpb25JZCI6ICJPTU4yMDA2MTEwMTM5NDUwMTIzNDU2Nzg5IiwKICAgICAgInN0YXRlIjogIk5PVElGSUVEIiwKICAgICAgImFtb3VudCI6IDM5OTAwLAogICAgICAibm90aWZpZWRBdCI6ICIxNjI4MjI5MTMyNjQ5IiwKICAgICAgInZhbGlkQWZ0ZXIiOiAiMTYyODIyOTEzMTAwMCIsCiAgICAgICJ2YWxpZFVwdG8iOiAiMTYyODU3NDczMTAwMCIKICAgIH0sCiAgICAic3Vic2NyaXB0aW9uRGV0YWlscyI6IHsKICAgICAgInN1YnNjcmlwdGlvbklkIjogIk9NUzIwMDYxMTAxMzk0NTAxMjM0NTY3ODkiLAogICAgICAic3RhdGUiOiAiQUNUSVZFIgogICAgfQogIH0KfQ=="
}
{
"success": true,
"code": "SUCCESS",
"message": "User debit notification is successful.",
"data": {
"callbackType": "NOTIFY",
"merchantId": "MID12345",
"transactionId": "TX1234567890",
"notificationDetails": {
"notificationId": "OMN2006110139450123456789",
"state": "NOTIFIED",
"amount": 39900,
"notifiedAt": "1628229132649",
"validAfter": "1628229131000",
"validUpto": "1628574731000"
},
"subscriptionDetails": {
"subscriptionId": "OMS2006110139450123456789",
"state": "ACTIVE"
}
}
}
{
"response": "ewogICJzdWNjZXNzIjogdHJ1ZSwKICAiY29kZSI6ICJTVUNDRVNTIiwKICAibWVzc2FnZSI6ICJQYXltZW50IEZhaWxlZCIsCiAgImRhdGEiOiB7CiAgICAiY2FsbGJhY2tUeXBlIjogIk5PVElGWSIsCiAgICAibWVyY2hhbnRJZCI6ICJNSUQxMjM0NSIsCiAgICAidHJhbnNhY3Rpb25JZCI6ICJUWDEyMzQ1Njc4OTAiLAogICAgIm5vdGlmaWNhdGlvbkRldGFpbHMiOiB7CiAgICAgICJub3RpZmljYXRpb25JZCI6ICJPTU4yMDA2MTEwMTM5NDUwMTIzNDU2Nzg5IiwKICAgICAgInN0YXRlIjogIkZBSUxFRCIsCiAgICAgICJhbW91bnQiOiAzOTkwMAogICAgfSwKICAgICJzdWJzY3JpcHRpb25EZXRhaWxzIjogewogICAgICAic3Vic2NyaXB0aW9uSWQiOiAiT01TMjAwNjExMDEzOTQ1MDEyMzQ1Njc4OSIsCiAgICAgICJzdGF0ZSI6ICJBQ1RJVkUiCiAgICB9CiAgfQp9"
}
{
"success": true,
"code": "SUCCESS",
"message": "Payment Failed",
"data": {
"callbackType": "NOTIFY",
"merchantId": "MID12345",
"transactionId": "TX1234567890",
"notificationDetails": {
"notificationId": "OMN2006110139450123456789",
"state": "FAILED",
"amount": 39900
},
"subscriptionDetails": {
"subscriptionId": "OMS2006110139450123456789",
"state": "ACTIVE"
}
}
}
Once you trigger Recurring INIT API 24 hours before the due date, You need to wait for the S2S Callback response from the Recurring INIT API and once the callback response is received check for the following:
- state parameter value should be NOTIFIED.
- Observe the value of the validAfter parameter.
Based on the value of the validAfter parameter you should call the Recurring Debit Execute API.
Important Note: Execution has to be done in validAfter to ValidUpto window only.