This API is used to set up the subscription for a user.
Host Details
Environment | Value |
---|---|
UAT | https://api-preprod.phonepe.com/apis/pg-sandbox |
PROD | https://api.phonepe.com/apis/pg |
API Endpoint
/subscriptions/v2/setup
Complete Host URL
Http Method: POST
Environment | Value |
---|---|
UAT | https://api-preprod.phonepe.com/apis/pg-sandbox/subscriptions/v2/setup |
PROD | https://api.phonepe.com/apis/pg/subscriptions/v2/setup |
Request Details
Request Headers
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 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) |
expireAt | DateTime | (in milliseconds) | No | Default value – 10 minutes |
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 | |
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 |
deviceContext.deviceOS | String | The type of device OS | Yes | Possible values ● ANDROID ● IOS |
metaInfo.udf1 | String | User defines fields propagated in status check & callbacks | No | Default Value – null |
Sample Request Payload
UPI Intent
{
"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"
},
"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 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"
}
}'
Sample Response (UPI Intent)
{
"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 | Description |
---|---|
orderId | PhonePe reference order ID |
state | Order state |
intentUrl | Intent URL for intent payment mode |
UPI Collect
{
"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"
},
"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": "999@ybl"
}
}
}
}
Sample 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": "999@ybl"
}
}
}
}'
Sample Response (UPI Collect)
{
"orderId" : "OMO2408072246197375675282",
"state" : "PENDING"
}
Response Parameters
Field Name | Description |
---|---|
orderId | PhonePe reference order ID |
state | Order state |