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	Min Value = 100 (in Paise)	Yes	The amount is in Paise. Note: • 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 and the first debit amount(In Paise)
`expireAt`	DateTime	(epoch in milliseconds)	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. For udf11 to udf15, alphanumeric values with _-+@. are allowed.
`paymentFlow`	Object	Additional details required by this flow	Yes
`deviceContext.deviceOS`	String	The type of device OS.	Yes	Possible values • Android • iOS

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

Request Parameters of metoInfo Object:

Parameter Name	Data Type	Description	Mandatory (Yes/No)	Constraints
`metaInfo.udf1-15`	String	Optional details you can add for more information	No	• Maximum length for Udf1-10 = 256 characters • Maximum length for Udf11-15 = 50 characters

⚠️ Do Not Rename metainfo Parameters!

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.

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

Request Parameters of paymentFlow Object:

Parameter Name	Data Type	Description	Mandatory	Constraints
`paymentFlow.type`	String	Type of payment flow.	Yes	Values Allowed: [SUBSCRIPTION_SETUP]
`paymentFlow.merchantSubscriptionId`	String	Unique merchant reference subscription ID – used for subscription status.	Yes
`paymentFlow.authWorkflowType`	String	Type of setup workflow.	Yes	Subscription auth type. Values: • PENNY_DROP • TRANSACTION
`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	Subscription frequency.	Yes	Possible Values : • DAILY • WEEKLY • MONTHLY • YEARLY • FORTNIGHTLY • BIMONTHLY • ON_DEMAND • QUARTERLY • HALFYEARLY
`paymentFlow.expireAt`	DateTime	Subscription cycle expiry. No operation allowed after subscription expires. (in milliseconds)	No	Default Value : 30 years
`paymentFlow.paymentMode`	Object	Payment mode details for setup.	Yes	Possible Values : { “type”: “UPI_INTENT”, “targetApp”: “com.phonepe.app” } { “type”: “UPI_COLLECT”, “details”: { “type”: “VPA”, “vpa”: “1234567890@ybl” } }
`paymentFlow.paymentMode.targetApp`	String	Target app for intent payment mode.	Yes	• Android: Package Name of the UPI 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"
}

You can also test this API request directly in Postman for a quick and easy integration check.

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.