post https://mercury-uat.phonepe.com/v3/recurring/subscription/create
Headers
| Field | Mandatory | Description |
|---|---|---|
Content-Type | Yes | application/json |
X-Verify | Yes | SHA256(base64 encoded payload + '/v3/recurring/subscription/create' + salt key) + '###' + salt index |
{
"merchantId": "MID12345",
"merchantSubscriptionId": "MSUB123456789012345",
"merchantUserId": "MU123456789",
"subscriptionName": "399 Platinum Plan",
"authWorkflowType": "PENNY_DROP",
"amountType": "FIXED",
"amount": 39900,
"frequency": "MONTHLY",
"recurringCount": 12,
"description": "Payment for 399 Platinum Plan",
"mobileNumber": "9xxxxxxxxx",
"subMerchantId": "DemoMerchant",
"deviceContext": {
"phonePeVersionCode": 400922
}
}
{
"merchantId": "MID12345",
"merchantSubscriptionId": "MSUB123456789012345",
"merchantUserId": "MU123456789",
"subscriptionName": "399 Platinum Plan",
"authWorkflowType": "PENNY_DROP",
"amountType": "FIXED",
"amount": 39900,
"frequency": "MONTHLY",
"recurringCount": 12,
"description": "Payment for 399 Platinum Plan",
"mobileNumber": "9xxxxxxxxx",
"subMerchantId": "DemoMerchant"
}
{
"request": "ewogICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAibWVyY2hhbnRTdWJzY3JpcHRpb25JZCI6ICJNU1VCMTIzNDU2Nzg5MDEyMzQ1IiwKICAibWVyY2hhbnRVc2VySWQiOiAiTVUxMjM0NTY3ODkiLAogICJzdWJzY3JpcHRpb25OYW1lIjogIjM5OSBQbGF0aW51bSBQbGFuIiwKICAiYXV0aFdvcmtmbG93VHlwZSI6ICJQRU5OWV9EUk9QIiwKICAiYW1vdW50VHlwZSI6ICJGSVhFRCIsCiAgImFtb3VudCI6IDM5OTAwLAogICJmcmVxdWVuY3kiOiAiTU9OVEhMWSIsCiAgInJlY3VycmluZ0NvdW50IjogMTIsCiAgImRlc2NyaXB0aW9uIjogIlBheW1lbnQgZm9yIDM5OSBQbGF0aW51bSBQbGFuIiwKICAibW9iaWxlTnVtYmVyIjogIjl4eHh4eHh4eHgiLAogICJzdWJNZXJjaGFudElkIjogIkRlbW9NZXJjaGFudCIsCiAgImRldmljZUNvbnRleHQiOiB7CiAgICAicGhvbmVQZVZlcnNpb25Db2RlIjogNDAwOTIyCiAgfQp9"
}
{
"request": "ewogICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAibWVyY2hhbnRTdWJzY3JpcHRpb25JZCI6ICJNU1VCMTIzNDU2Nzg5MDEyMzQ1IiwKICAibWVyY2hhbnRVc2VySWQiOiAiTVUxMjM0NTY3ODkiLAogICJzdWJzY3JpcHRpb25OYW1lIjogIjM5OSBQbGF0aW51bSBQbGFuIiwKICAiYXV0aFdvcmtmbG93VHlwZSI6ICJQRU5OWV9EUk9QIiwKICAiYW1vdW50VHlwZSI6ICJGSVhFRCIsCiAgImFtb3VudCI6IDM5OTAwLAogICJmcmVxdWVuY3kiOiAiTU9OVEhMWSIsCiAgInJlY3VycmluZ0NvdW50IjogMTIsCiAgImRlc2NyaXB0aW9uIjogIlBheW1lbnQgZm9yIDM5OSBQbGF0aW51bSBQbGFuIiwKICAibW9iaWxlTnVtYmVyIjogIjl4eHh4eHh4eHgiLAogICJzdWJNZXJjaGFudElkIjogIkRlbW9NZXJjaGFudCIKfQ=="
}
For Subscription - PhonePe Intent Flow,
In the Create User Subscription API request payload, the deviceContext parameter MUST be passed.
Also, in the Create User Subscription API response, merchants MUST rely on the isSupportedApp and isSupportedUser parameters. Only if both the parameters are TRUE, the PhonePe option MUST be shown on the Checkout page.
For Subscription - Open Intent Flow and Collect Flow
In the Create User Subscription API request payload, the deviceContext parameter is not required.
Also, in the Create User Subscription API response, Merchants need not rely on the isSupportedApp and isSupportedUser parameters.
Request Parameters
| Field Name | Data Type | Mandatory | Description |
|---|---|---|---|
merchantId | String | Yes | Unique Id assigned to the merchant in the PhonePe system. Assigned during merchant onboarding. |
merchantSubscriptionId | String | Yes | Unique Merchant Subscription Id generated by the merchant |
merchantUserId | String | Yes | Unique Merchant User Id with PhonePe user would be linked |
subscriptionName | String | No | Plan/Subscription title, which would be shown to user during Auth |
authWorkflowType | String | Yes | Subscription auth type. Values: ● PENNY_DROP ● TRANSACTION |
amountType | String | Yes | Recurring debit/redemption amount type. Values: ● FIXED ● VARIABLE |
amount | Long | Yes | The MAXIMUM debit/redemption amount for the mandate. Amount is in Paise. For VARIABLE recurring debit, this amount would be considered as Max Cap Amount |
frequency | String | Yes | Recurring frequency Values: ● DAILY ● WEEKLY ● FORTNIGHTLY ● MONTHLY ● QUARTERLY ● HALFYEARLY ● YEARLY ● ON_DEMAND |
recurringCount | Integer | Yes | Max Recurring Instalments. [ Total Time Span = frequency * recurringCount ] Note: 30 years is the max lifetime of a subscription. Example: For Yearly, max Recurring Count can be 30. |
subMerchantId | String | No | Sub merchant Id |
description | String | No | Merchant’s subscription message or description |
mobileNumber | String | Conditonal | Mobile number of the user. [Mandatory] For Subscription - PhonePe Intent Flow. [Non Mandatory] For Subscription - Open Intent Flow and Collect Flow |
deviceContext.phonePeVersionCode | Long | Conditonal | The user’s PhonePe app version. Refer here [Mandatory] For Subscription - PhonePe Intent Flow. [Non Mandatory] For Subscription - Open Intent Flow and Collect Flow |
{
"success": true,
"code": "SUCCESS",
"message": "Your request has been successfully completed. [message = Your subscription request has been successfully created.]",
"data": {
"subscriptionId": "OMS2105261046487942524798",
"state": "CREATED",
"validUpto": 1622007108794,
"isSupportedApp": true,
"isSupportedUser": true
}
}
Response Parameters
| Field Name | Data Type | Description |
|---|---|---|
| isSupportedApp | Boolean | PhonePe app installed on User’s device supports subscription |
| isSupportedUser | Boolean | User can set the subscription |
| subscriptionId | String | PhonePe subscription identifier |
| state | String | CREATED |
| validUpto | DateTime | Epoch time until which auth must be completed |
| code | String | "SUCCESS", "INVALID_TRANSACTION_ID", “INVALID_START_DATE” |