Recurring 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

{
  "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.

Language
Click Try It! to start a request and see the response here!