Create User Subscription

Headers

Field	Mandatory	Description
`Content-Type`	`Yes`	application/json
`X-Verify`	`Yes`	SHA256(base64 encoded payload + ‘/v3/recurring/subscription/create’ + salt key) + ‘###’ + salt index

PhonePe Intent – Create Subscription Request

{
  "merchantId": "MID12345",
  "merchantSubscriptionId": "MSUB123456789012345",
  "merchantUserId": "MU123456789",
  "authWorkflowType": "PENNY_DROP",		  //PENNY_DROP or TRANSACTION
  "amountType": "FIXED",		          //FIXED or VARIABLE
  "amount": 39900,
  "frequency": "MONTHLY",
  "recurringCount": 12,
  "mobileNumber": "9xxxxxxxxx",
  "deviceContext": {
  "phonePeVersionCode": 400922		         //Only for ANDROID 
  }
}

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.

{
  "request": "ewogICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAibWVyY2hhbnRTdWJzY3JpcHRpb25JZCI6ICJNU1VCMTIzNDU2Nzg5MDEyMzQ1IiwKICAibWVyY2hhbnRVc2VySWQiOiAiTVUxMjM0NTY3ODkiLAogICJhdXRoV29ya2Zsb3dUeXBlIjogIlBFTk5ZX0RST1AiLAogICJhbW91bnRUeXBlIjogIkZJWEVEIiwKICAiYW1vdW50IjogMzk5MDAsCiAgImZyZXF1ZW5jeSI6ICJNT05USExZIiwKICAicmVjdXJyaW5nQ291bnQiOiAxMiwKICAibW9iaWxlTnVtYmVyIjogIjl4eHh4eHh4eHgiLAogICJkZXZpY2VDb250ZXh0IjogewogICAgInBob25lUGVWZXJzaW9uQ29kZSI6IDQwMDkyMiwKICAgICJkZXZpY2VPUyIgOiAiQU5EUk9JRCIKICB9Cn0="
}

For Subscription – PhonePe Intent Flow,

[Android Only] In the Create User Subscription API request payload, the deviceContext parameter MUST be passed.
[Android Only] 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.

Open Intent or Collect – Create Subscription Request

{
  "merchantId": "MID12345",
  "merchantSubscriptionId": "MSUB123456789012345",
  "merchantUserId": "MU123456789",
  "authWorkflowType": "PENNY_DROP",	          //PENNY_DROP or TRANSACTION
  "amountType": "FIXED",		          //FIXED or VARIABLE
  "amount": 39900,
  "frequency": "MONTHLY",
  "recurringCount": 12,
  "mobileNumber": "9xxxxxxxxx"
}

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.

{
  "request": "ewogICJtZXJjaGFudElkIjogIk1JRDEyMzQ1IiwKICAibWVyY2hhbnRTdWJzY3JpcHRpb25JZCI6ICJNU1VCMTIzNDU2Nzg5MDEyMzQ1IiwKICAibWVyY2hhbnRVc2VySWQiOiAiTVUxMjM0NTY3ODkiLAogICJhdXRoV29ya2Zsb3dUeXBlIjogIlBFTk5ZX0RST1AiLAogICJhbW91bnRUeXBlIjogIkZJWEVEIiwKICAiYW1vdW50IjogMzk5MDAsCiAgImZyZXF1ZW5jeSI6ICJNT05USExZIiwKICAicmVjdXJyaW5nQ291bnQiOiAxMiwKICAibW9iaWxlTnVtYmVyIjogIjl4eHh4eHh4eHgiCn0="
}

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
`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. The amount is in Paise. Note: ● For VARIABLE recurring debit, this amount would be considered as Max Cap Amount ● For PENNY_DROP flow, the amount should be greater than or equal to 200 (In Paise) ● For TRANSACTION flow, the amount should be greater than or equal to 100 (In Paise)
`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
`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. [Mandatory – Android] 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”

{“method”:”post”,”url”:”/v3/recurring/subscription/create”,”auth”:”required”,”results”:{“codes”:[{“name”:””,”code”:”{\n \”success\”: true,\n \”code\”: \”SUCCESS\”,\n \”message\”: \”Your request has been successfully completed. [message = Your subscription request has been successfully created.]\”,\n \”data\”: {\n \”subscriptionId\”: \”OMS2105131257131014108471\”,\n \”state\”: \”CREATED\”,\n \”validUpto\”: 1620891733101,\n \”isSupportedApp\”: true,\n \”isSupportedUser\”: true\n }\n}”,”language”:”json”,”status”:200},{“name”:””,”code”:”{\n \”success\”: false,\n \”code\”: \”BAD_REQUEST\”,\n \”message\”: \”may not be empty.\”,\n \”data\”: {}\n}”,”language”:”json”,”status”:400}]},”params”:[{“name”:”Content-Type”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”application/json”,”required”:true,”in”:”header”,”ref”:””,”_id”:”60aca53d42152e003462b6ed”},{“name”:”X-Verify”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”SHA256(base64 encoded payload + /v3/recurring/subscription/create + salt key) + ### + salt index”,”required”:true,”in”:”header”,”ref”:””,”_id”:”60aca53d42152e003462b6ec”},{“name”:”request”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”base64 encoded payload”,”required”:true,”in”:”body”,”ref”:””,”_id”:”60aca53d42152e003462b6e7″}],”examples”:{“codes”:[]},”apiSetting”:”63bb01b11abcf7046d98754c”}

https://api-preprod.phonepe.com/apis/pg-sandbox

Headers

PhonePe Intent – Create Subscription Request

Open Intent or Collect – Create Subscription Request

Request Parameters

Response Parameters

Updated on Nov 02, 2023