Create User Subscription

Headers

FieldMandatoryDescription
Content-TypeYesapplication/json
X-VerifyYesSHA256(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 NameData TypeMandatoryDescription
merchantIdStringYesUnique Id assigned to the merchant in the PhonePe system. Assigned during merchant onboarding.
merchantSubscriptionIdStringYesUnique Merchant Subscription Id generated by the merchant
merchantUserIdStringYesUnique Merchant User Id with PhonePe
user would be linked
subscriptionNameStringYesPlan/Subscription title, which would be
shown to user during Auth
authWorkflowTypeStringYesSubscription auth type.
Values:
● PENNY_DROP
● TRANSACTION
amountTypeStringYesRecurring debit/redemption amount
type.
Values:
● FIXED
● VARIABLE
amountLongYesThe MAXIMUM debit/redemption amount for the mandate.
Amount is in Paise.
For VARIABLE recurring debit, this amount would be considered as Max Cap Amount
frequencyStringYesRecurring frequency
Values:
● DAILY
● WEEKLY
● FORTNIGHTLY
● MONTHLY
● QUARTERLY
● HALFYEARLY
● YEARLY
● ON_DEMAND
recurringCountIntegerYesMax 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.
subMerchantIdStringNoSub merchant Id
descriptionStringNoMerchant’s subscription message or
description
mobileNumberStringConditonalMobile number of the user.
[Mandatory] For Subscription - PhonePe Intent Flow.

[Non Mandatory] For Subscription - Open Intent Flow and Collect Flow
deviceContext.phonePeVersionCodeLongConditonalThe 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 NameData TypeDescription
isSupportedAppBooleanPhonePe app installed on User’s device supports subscription
isSupportedUserBooleanUser can set the subscription
subscriptionIdStringPhonePe subscription identifier
stateStringCREATED
validUptoDateTimeEpoch time until which auth must be completed
codeString"SUCCESS",
"INVALID_TRANSACTION_ID",
“INVALID_START_DATE”
Language
Click Try It! to start a request and see the response here!