Create User Subscription (iOS)

To set up the mandate or accept the first payment from the user on the iOS Platform

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" : "MERCHANTUAT",
  "merchantSubscriptionId" : "0C6D8F0DAF649D590249D0C708481B8",
  "merchantUserId" : "5330F4FB-C66C-4646-8691-11544B580547",
  "subscriptionName" : "499 Gold PLan",
  "authWorkflowType" : "TRANSACTION",
  "amountType" : "FIXED",
  "amount" : 39900,
  "frequency" : "MONTHLY",
  "recurringCount" : "12",
  "description" : "Payment for 499 Gold PLan",
  "mobileNumber" : "9999999999",
  "deviceContext" : {
    "deviceOS" : "IOS"
  }
}

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": "ewogICJtZXJjaGFudElkIiA6ICJNRVJDSEFOVFVBVCIsCiAgIm1lcmNoYW50U3Vic2NyaXB0aW9uSWQiIDogIjBDNkQ4RjBEQUY2NDlENTkwMjQ5RDBDNzA4NDgxQjgiLAogICJtZXJjaGFudFVzZXJJZCIgOiAiNTMzMEY0RkItQzY2Qy00NjQ2LTg2OTEtMTE1NDRCNTgwNTQ3IiwKICAic3Vic2NyaXB0aW9uTmFtZSIgOiAiNDk5IEdvbGQgUExhbiIsCiAgImF1dGhXb3JrZmxvd1R5cGUiIDogIlRSQU5TQUNUSU9OIiwKICAiYW1vdW50VHlwZSIgOiAiRklYRUQiLAogICJhbW91bnQiIDogMzk5MDAsCiAgImZyZXF1ZW5jeSIgOiAiTU9OVEhMWSIsCiAgInJlY3VycmluZ0NvdW50IiA6ICIxMiIsCiAgImRlc2NyaXB0aW9uIiA6ICJQYXltZW50IGZvciA0OTkgR29sZCBQTGFuIiwKICAibW9iaWxlTnVtYmVyIiA6ICI5OTk5OTk5OTk5IiwKICAiZGV2aWNlQ29udGV4dCIgOiB7CiAgICAiZGV2aWNlT1MiIDogIklPUyIKICB9Cn0K"
}

For Subscription – PhonePe Intent Flow,

In the Create User Subscription API request payload, the deviceContext parameter MUST be passed.
Display PhonePe App on the checkout page only when isPPAppPresent of the deviceContext returns TRUE and isSupportedUser flag is TRUE.

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`	`Yes`	Plan/Subscription title, which would be shown to user during Auth [Note: Max length should be less than 63 characters]
`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.
`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`	`Object`	`Yes`
`deviceContext.deviceOS`	`String`	`Yes`	Value will be “IOS”

{
    "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”:”5a1563aec32b6d002a16fb67″}

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

Headers

PhonePe Intent – Create Subscription Request

Request Parameters

Response Parameters

Updated on Sep 22, 2023