Create User Subscription
post https://api-preprod.phonepe.com/apis/pg-sandbox/v3/recurring/subscription/create

anchor image
Copied !
FieldMandatoryDescription
Content-TypeYesapplication/json
X-VerifyYesSHA256(base64 encoded payload + ‘/v3/recurring/subscription/create’ + salt key) + ‘###’ + salt index

PhonePe Intent – Create Subscription Request

Sample Payload for Base64 - PhonePe Intent
{
  "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.

Sample Request- PhonePe Intent
{
  "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

Sample Payload for Base64 - Open Intent or Collect Flow
{
  "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.

Sample Request- Open Intent or Collect Flow
{
  "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.
anchor image
Copied !
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
authWorkflowTypeStringYesSubscription auth type.
Values:
● PENNY_DROP
● TRANSACTION
amountTypeStringYesRecurring debit/redemption amount
type.
Values:
● FIXED
● VARIABLE
amountLongYes
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)
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
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.
[Mandatory – Android] For Subscription – PhonePe Intent Flow.

[Non Mandatory] For Subscription – Open Intent Flow and Collect Flow

Sample Response
{
    "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
    }
}
anchor image
Copied !
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”,
“DUPLICATE_SUBSCRIPTION_CREATE_REQUEST”,
{“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
Content-Type string required
application/json
X-Verify string required
SHA256(base64 encoded payload + /v3/recurring/subscription/create + salt key) + ### + salt index

BODY PARAMS
request string required
base64 encoded payload
Response
close
RESPONSE BODY
success boolean
code string
message string
data Object
subscriptionId string
state string
validUpto number
isSupportedApp boolean
isSupportedUser boolean

RESPONSES
Code 200
200
Code 400
400

Updated on Nov 02, 2023