Recurring INIT
post https://api-preprod.phonepe.com/apis/pg-sandbox/v3/recurring/debit/init

To notify in advance the user about the recurring debit. The API can also be used to debit the amount.
anchor image
Copied !
Header NameMandatoryHeader Value
Content-TypeYesapplication/json
X-VerifyYesSHA256(base64 encoded payload + “/v3/recurring/debit/init” + salt key) + ### + salt index
X-CALLBACK-URLYesThe callback URL to receive the server to server callback response.
Sample Payload for Base64
{ "merchantId": "MID12345", "merchantUserId": "U123456789", "subscriptionId": "OMS2006110139450123456789", "transactionId": "TX1234567890", "autoDebit": true, "amount": 39900 }

Convert the JSON Payload to Base64 Encoded Payload.

The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.

Sample Request
{ "request":"ewogICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAibWVyY2hhbnRVc2VySWQiOiAiVTEyMzQ1Njc4OSIsCiAgInN1YnNjcmlwdGlvbklkIjogIk9NUzIwMDYxMTAxMzk0NTAxMjM0NTY3ODkiLAogICJ0cmFuc2FjdGlvbklkIjogIlRYMTIzNDU2Nzg5MCIsCiAgImF1dG9EZWJpdCI6IHRydWUsCiAgImFtb3VudCI6IDM5OTAwCn0=" }
anchor image
Copied !
Field NameData TypeMandatoryDescriptionComments
merchantIdStringYesMID provided by PhonePe
merchantUserIdStringYesUser’s unique Id maintained by merchant
subscriptionIdStringYesPhonePe subscription Id
transactionIdStringYesMerchant’s unique transaction Id
amountLongYesThe redemption amount of the mandate
autoDebitBooleanNo
(Optional)
Default: false
Values: true/false
When this flag is set
no debit/execute
would be needed or
allowed
Sample Response
{ "success": true, "code": "SUCCESS", "message": "Your request has been successfully submitted.", "data": { "notificationId": "OMN2006110154420123456789", "state": "ACCEPTED", "amount": 39900 } }
anchor image
Copied !
Field NameData TypeDescription
notificationIdStringMerchant’s SubscriptionId
amountLongAmount
stateString● ACCEPTED
● FAILED
notifiedAtLongEpoch time when the user is notified.
validAfterLongEpoch time when the user is notified.
validUptoLongEpoch time after which the user cannot be debited.
anchor image
Copied !

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

Sample S2S Callback Response - SUCCESSFUL Notification
{ "response": "ewogICAgInN1Y2Nlc3MiOiB0cnVlLAogICAgImNvZGUiOiAiU1VDQ0VTUyIsCiAgICAibWVzc2FnZSI6ICJVc2VyIGRlYml0IG5vdGlmaWNhdGlvbiBpcyBzdWNjZXNzZnVsLiIsCiAgICAiZGF0YSI6IHsKICAgICAgICAiY2FsbGJhY2tUeXBlIjogIk5PVElGWSIsCiAgICAgICAgIm1lcmNoYW50SWQiOiAiTUlEMTIzNDUiLAogICAgICAgICJ0cmFuc2FjdGlvbklkIjogIlRYMTIzNDU2Nzg5MCIsCiAgICAgICAgIm5vdGlmaWNhdGlvbkRldGFpbHMiOiB7CiAgICAgICAgICAgICJub3RpZmljYXRpb25JZCI6ICJPTU4yMDA2MTEwMTM5NDUwMTIzNDU2Nzg5IiwKICAgICAgICAgICAgInN0YXRlIjogIk5PVElGSUVEIiwKICAgICAgICAgICAgImFtb3VudCI6IDM5OTAwLAogICAgICAgICAgICAibm90aWZpZWRBdCI6IDE2MjgyMjkxMzI2NDksCiAgICAgICAgICAgICJ2YWxpZEFmdGVyIjogMTYyODIyOTEzMTAwMCwKICAgICAgICAgICAgInZhbGlkVXB0byI6IDE2Mjg1NzQ3MzEwMDAKICAgICAgICB9LAogICAgICAgICJzdWJzY3JpcHRpb25EZXRhaWxzIjogewogICAgICAgICAgICAic3Vic2NyaXB0aW9uSWQiOiAiT01TMjAwNjExMDEzOTQ1MDEyMzQ1Njc4OSIsCiAgICAgICAgICAgICJzdGF0ZSI6ICJBQ1RJVkUiCiAgICAgICAgfQogICAgfQp9" }
Base64 Decoded Response - SUCCESSFUL Notification
{ "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" } } }
Sample S2S Callback Response - FAILED Notification
{ "response": "ewogICJzdWNjZXNzIjogdHJ1ZSwKICAiY29kZSI6ICJTVUNDRVNTIiwKICAibWVzc2FnZSI6ICJQYXltZW50IEZhaWxlZCIsCiAgImRhdGEiOiB7CiAgICAiY2FsbGJhY2tUeXBlIjogIk5PVElGWSIsCiAgICAibWVyY2hhbnRJZCI6ICJNSUQxMjM0NSIsCiAgICAidHJhbnNhY3Rpb25JZCI6ICJUWDEyMzQ1Njc4OTAiLAogICAgIm5vdGlmaWNhdGlvbkRldGFpbHMiOiB7CiAgICAgICJub3RpZmljYXRpb25JZCI6ICJPTU4yMDA2MTEwMTM5NDUwMTIzNDU2Nzg5IiwKICAgICAgInN0YXRlIjogIkZBSUxFRCIsCiAgICAgICJhbW91bnQiOiAzOTkwMCwKICAgICAgInBheVJlc3BvbnNlQ29kZSIgOiAiWjkiCiAgICB9LAogICAgInN1YnNjcmlwdGlvbkRldGFpbHMiOiB7CiAgICAgICJzdWJzY3JpcHRpb25JZCI6ICJPTVMyMDA2MTEwMTM5NDUwMTIzNDU2Nzg5IiwKICAgICAgInN0YXRlIjogIkFDVElWRSIKICAgIH0KICB9Cn0=" }
Base64 Decoded Response - FAILED Notification
{ "success": true, "code": "SUCCESS", "message": "Payment Failed", "data": { "callbackType": "NOTIFY", "merchantId": "MID12345", "transactionId": "TX1234567890", "notificationDetails": { "notificationId": "OMN2006110139450123456789", "state": "FAILED", "amount": 39900, "payResponseCode" : "Z9" }, "subscriptionDetails": { "subscriptionId": "OMS2006110139450123456789", "state": "ACTIVE" } } }

If autoDebit flag is FALSE

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.

If autoDebit flag is True

Once you trigger Recurring INIT API 24 hours before the due date

  • If the Notification is successful sent, you will not receive the Notification Webhook response instead you need to wait for the final S2S Callback response of Recurring Debit.
  • If the Notification failed, then you will receive Notification Failure Webhook response and once the callback response is received check for the following:
    • state parameter value should be FAILED.
Key notes
  • For the fixed frequencies like MONTHLY, QUARTERLY, YEARLY etc., except DAILY,  merchants can debit only once in that frequency. If incase called multiple times then the response SUBSCRIPTION_RECURRENCE_LIMIT_BREACHED will be received.Example: For MONTHLY frequency, there can be maximum of only one debit in a calendar month.

  • For the fixed frequencies like MONTHLY, QUARTERLY, YEARLY etc., except DAILY, the calendar month will only be applicable.Example: For MONTHLY frequency, if there is a successful debit placed on 28th October, then there can’t be another debit possible on the same October month.

{“method”:”post”,”url”:”/v3/recurring/debit/init”,”auth”:”required”,”results”:{“codes”:[{“name”:””,”code”:”{\n \”success\”: true,\n \”code\”: \”SUCCESS\”,\n \”message\”: \”Your request has been successfully submitted.\”,\n \”data\”: {\n \”notificationId\”: \”OMN2006110154420123456789\”,\n \”state\”: \”ACCEPTED\”,\n \”amount\”: 39900\n }\n}”,”language”:”json”,”status”:200},{“name”:””,”code”:”{\n \”success\”: false,\n \”code\”: \”SUBSCRIPTION_NOT_FOUND\”,\n \”message\”: \”No Subscription found with the given details.\”,\n \”data\”: {}\n}”,”language”:”json”,”status”:400}]},”params”:[{“name”:”Content-Type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”60af0fdbac97200078c225d5″},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”SHA256(base64 encoded payload + \”/v3/recurring/debit/init\” + salt key) + ### + salt index”,”required”:true,”in”:”header”,”ref”:””,”_id”:”60af0fdbac97200078c225d4″},{“name”:”request”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”base64 encoded payload”,”required”:true,”in”:”body”,”ref”:””,”_id”:”60b75a934705b7023bdf78f2″},{“name”:”X-CALLBACK-URL”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”Dynamic callback URL for server to server callback”,”required”:false,”in”:”header”,”ref”:””,”_id”:”60ed800f826d6d00472f60ac”}],”apiSetting”:”63bb01b11abcf7046d98754c”,”examples”:{“codes”:[]}}
https://api-preprod.phonepe.com/apis/pg-sandbox

HEADERS
Content-Type string required
X-VERIFY string required
SHA256(base64 encoded payload + "/v3/recurring/debit/init" + salt key) + ### + salt index
X-CALLBACK-URL string
Dynamic callback URL for server to server callback

BODY PARAMS
request string required
base64 encoded payload

RESPONSES
Code 200
200
Code 400
400