Setup Subscription

This API is used to set up a subscription for a customer. You will have to configure UPI Intent and UPI Collect. For UPI Collect, the customer’s UPI VPA (Virtual Payment Address) must be validated before initiating the UPI Collect request.

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

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	(in milliseconds)	No	Default value – 10 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": 1709058548000,
    "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"
    },
    "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"
    }
}

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": 1709058548000,
   "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"
}

UPI Address Validate API

Use this API to validate the customer’s UPI VPA. This verification must be completed before initiating a UPI Collect transaction.

Environment for UPI Address Validate API

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

Request for UPI Address Validate API

Request Headers

Header Name	Header Value
Content-Type	application/json
Authorization	O-Bearer <access_token>

Request Parameters

Parameter Name	Data Type	Description	Mandatory (Yes/No)	Constraints
`type`	String	Type of UPI Payment Address.	Yes	Values allowed: [VPA]
`vpa`	String	VPA of user to validate.	Yes	Max Length: 255

Sample Request

{
    "type": "VPA",
    "vpa": "****@ybl" //add success@ybl/failure@ybl/pending@ybl here.
}

📘 Simulating PhonePe Mandate Responses!

In the UAT environment, you will not receive an actual collect request. The system provides a mocked API response that is simulated based on the VPA address you enter.

To test the different scenarios, please follow these steps:

In the VPA Address field, enter one of the following test VPAs:
- Success@ybl (Simulates a successful validation and mandate creation)
- Failure@ybl (Simulates a failed validation)
- Pending@ybl (Simulates a pending or in-progress response)
After submitting, the API will return a corresponding response based on the VPA you entered.
Please verify that the subscription status correctly reflects that API response.

Response for UPI Address Validate API

Case 1: Sample Response for VPA is Valid

{
    "valid": true,
    "name": "<Name of User>"
}

Case 2: Sample Response for Invalid VPA

{    
    "valid": false
}

Response Parameters

Parameter Name	Data Type	Description	Mandatory	Constraints
`type`	String	Type of UPI Payment Address	Yes	Client ID shared by PhonePe PG
`vpa`	String	VPA of user to validate	Yes	Max Length: 255

UPI Collect

Sample Request

{
    "merchantOrderId": "MO1709025691805",
    "amount": 200,
    "expireAt": 1709058548000,
    "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": "additional-information-6",
        "udf7": "additional-information-7",
        "udf8": "additional-information-8",
        "udf9": "additional-information-9",
        "udf10": "additional-information-10",
        "udf11": "additional-information-11",
        "udf12": "additional-information-12",
        "udf13": "additional-information-13",
        "udf14": "additional-information-14",
        "udf15": "additional-information-15"
    },
    "paymentFlow": {
        "type": "SUBSCRIPTION_SETUP",
        "merchantSubscriptionId": "MS1709025691805",
        "authWorkflowType": "TRANSACTION",
        "amountType": "VARIABLE",
        "maxAmount": 2000,
        "frequency": "ON_DEMAND",
        "expireAt": 1737278524000,
        "paymentMode": {
            "type": "UPI_COLLECT",
            "details": {
                "type": "VPA",
                "vpa": "****@ybl" //add success@ybl/failure@ybl/pending@ybl here.
            }
        }
    }
}

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-raw '{
   "merchantOrderId": "MO1709025691805",
   "amount": 200,
   "expireAt": 1709058548000,
   "paymentFlow": {
       "type": "SUBSCRIPTION_SETUP",
       "merchantSubscriptionId": "MS1709025691805",
       "authWorkflowType": "TRANSACTION",
       "amountType": "VARIABLE",
       "maxAmount": 2000,
       "frequency": "ON_DEMAND",
       "expireAt": 1737278524000,
       "paymentMode": {
           "type": "UPI_COLLECT",
           "details": {
               "type": "VPA",
                "vpa": "****@ybl" //add success@ybl/failure@ybl/pending@ybl here.
           }
       }
   }
}

Response for UPI Collect

Sample Response

{
    "orderId" : "OMO2408072246197375675282",
    "state" : "PENDING"
}

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 about the two types of order status APIs provided by PhonePe to track subscription actions. These will help you monitor the progress of both subscription setup and redemption requests in real time.