Setup Subscription

This API is used to set up a subscription for a user.

Environment

Environment	HTTP Method	API
Sandbox	`POST`	https://api-preprod.phonepe.com/apis/pg-sandbox/subscriptions/v2/setup
Production	`POST`	https://api.phonepe.com/apis/pg/subscriptions/v2/setup

Request

Header Name	Header Value	Description
Content-Type	application/json
Authorization	O-Bearer <access_token>	Pass access_token received in Authorization call

⚠️ For Partner Integrations!

It is mandatory to include the X-MERCHANT-ID header with the MerchantID of the end merchant.

Request Parameters

Parameter Name	Data Type	Description	Mandatory	Constraints
`merchantOrderId`	String	Unique merchant order id generated by merchant.	Yes	• Max Length = 63 characters. • No Special characters allowed except underscore “_” and hyphen “-“
`amount`	Long	Order amount in paisa to setup a mandate based on the `authWorkflowType`.	Yes	• For PENNY_DROP flow, the amount should be equal to 200 (In Paise) • For TRANSACTION flow, the amount should be greater than or equal to 100 or the first debit amount(In Paise)
`expireAt`	DateTime	Order expiry in seconds. If not passed default value will be used.	No	Default value = 5 minutes
`metaInfo`	Object	Merchant defined meta info to store additional information. Same data will be returned in status and callback response.	No	• For udf1 to udf10, there is no constraint. Maximum length = 256 characters • For udf11 to udf15, alphanumeric values with _-+@. are allowed. Maximum length = 50 characters Note: It is mandatory to keep the parameter names udf1, udf2, etc., exactly as they are in the `metainfo` block. Renaming these key values will result in a production error.
`paymentFlow`	Object	Additional details required by this flow	Yes
`deviceContext.deviceOS`	String	The type of device OS.	Yes	Allowed values: • Android • iOS

The paymentFlow object contains additional parameters, which are explained in the table below.

`paymentFlow.type`	String	Type of payment flow.	Yes	Allowed values = [SUBSCRIPTION_SETUP]
`paymentFlow.merchantSubscriptionId`	String	Unique merchant reference subscription ID – used for subscription status.	Yes
`paymentFlow.authWorkflowType`	String	Defines the type of workflow verification whether it is TRANSACTION or PENNY DROP	Yes	Allowed values = “TRANSACTION” or “PENNY DROP”
`paymentFlow.amountType`	String	Nature of redemption amount.	Yes	Possible Values : • FIXED • VARIABLE
`paymentFlow.maxAmount`	Long	Max amount upto which redemptions will be allowed.	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
`paymentFlow.frequency`	String	Defines the Redemption Frequency.	Yes	Allowed values = • DAILY • WEEKLY • MONTHLY • FORTNIGHTLY • BIMONTHLY • QUARTERLY • HALFYEARLY • YEARLY • ONDEMAND
`paymentFlow.expireAt`	DateTime	Defines Subscription cycle expiry. No operation allowed after subscription expires. (in milliseconds)	No	Default Value= 30 years
`paymentFlow.paymentMode`	Object	Defines payment mode details for setup.	Yes	Allowed Value = { “type”: “UPI_INTENT” }
`paymentFlow.paymentMode.targetApp`	String	Defines target app for intent payment mode.	Yes	• Android: Package Name of the UPI app. { “targetApp”: “com.phonepe.app” } • iOS: Static Values like [PHONEPE, GPAY, PAYTM, CRED, SUPERMONEY, BHIM, AMAZON]

UPI Intent

Sample Request

{
    "merchantOrderId": "MO1709025658932",
    "amount": 200,
    "expireAt": 1770388701000,
    "paymentFlow": {
        "type": "SUBSCRIPTION_SETUP",
        "merchantSubscriptionId": "MS1709025658932",
        "authWorkflowType": "TRANSACTION",
        "amountType": "FIXED",
        "maxAmount": 200,
        "frequency": "ON_DEMAND",
        "expireAt": 1770392301000,
        "paymentMode": {
            "type": "UPI_INTENT",
            "targetApp": "com.phonepe.app"
        }
    },
    "deviceContext": {
        "deviceOS": "ANDROID"
    },
    "metaInfo": {
        "udf1": "some meta info of max length 256",
        "udf2": "some meta info of max length 256",
        "udf3": "some meta info of max length 256",
        "udf4": "some meta info of max length 256",
        "udf5": "some meta info of max length 256",
        "udf6": "some meta info of max length 256",
        "udf7": "some meta info of max length 256",
        "udf8": "some meta info of max length 256",
        "udf10": "some meta info of max length 256",
        "udf11": "some meta info of max length 50",
        "udf12": "some meta info of max length 50",
        "udf13": "some meta info of max length 50",
        "udf14": "some meta info of max length 50",
        "udf15": "some meta info of max length 50"
    }
}

Sample Request in CURL

curl --location 'https://api-preprod.phonepe.com/apis/pg-sandbox/subscriptions/v2/setup' \
--header 'Accept: application/json' \
--header 'Authorization: O-Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHBpcmVzT24iOjE3MTIyNTM2MjU2NDQsIm1lcmNoYW50SWQiOiJWMlNVQlVBVCJ9.7aVzYI_f_77-bBicEcRNuYx093b2wCsgl_WFNkKqAPY' \
--header 'Content-Type: application/json' \
--data '{
   "merchantOrderId": "MO1443709025658932",
   "amount": 200,
   "expireAt": 170905854,
   "paymentFlow": {
       "type": "SUBSCRIPTION_SETUP",
       "merchantSubscriptionId": "MS1709025658932",
       "authWorkflowType": "TRANSACTION",
       "amountType": "FIXED",
       "maxAmount": 200,
       "frequency": "ON_DEMAND",
       "expireAt": 1737278524000,
       "paymentMode": {
           "type": "UPI_INTENT",
           "targetApp": "com.phonepe.app"
       }
   },
    "deviceContext" : {
        "deviceOS" : "ANDROID"
    }
}'

Response for UPI Intent

Sample Response

{
    "orderId" : "OMO2408072246197375675282",
    "state" : "PENDING",
    "intentUrl" : "ppesim://mandate?pa=VRUAT@ybl&pn=SUBSCRIBEMID&am=300&mam=&tr=OM2408072246197385675168&utm_campaign=SUBSCRIBE_AUTH&utm_medium=VRUAT&utm_source=OM2408072246197385675168"
}

Response Parameters

Field Name	Data Type	Description
`orderId`	String	Internal order ID generated by PhonePe Payment Gateway.
`state`	String	State of the order created, expected value is PENDING.
`redirectUrl`	String	Intent url to invoke the payment app that initiates the mandate and completes the payment.

What’s Next?

In the next section, you will learn how to you check whether the subscription has been successfully created, is still pending user action, has failed, or is complete.