Subscription Setup

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

Host Details

EnvironmentValue
UAThttps://api-preprod.phonepe.com/apis/pg-sandbox
PRODhttps://api.phonepe.com/apis/pg

API Endpoint

/subscriptions/v2/setup

Complete Host URL

Http Method: POST

EnvironmentValue
UAThttps://api-preprod.phonepe.com/apis/pg-sandbox/subscriptions/v2/setup
PRODhttps://api.phonepe.com/apis/pg/subscriptions/v2/setup

Request Details

Request Headers

Header NameHeader ValueDescription
Content-Typeapplication/json
AuthorizationO-Bearer <access_token>Pass access_token received in Authorization call

Request Parameters

Parameter NameData TypeDescriptionMandatoryConstraints
merchantOrderIdStringUnique merchant order id generated by merchantYesMax Length = 63 characters
No Special characters allowed except underscore “_” and hyphen “-“
amountLongMin Value = 100 (in Paise)YesThe 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)
expireAtDateTime(in milliseconds)NoDefault value – 10 minutes
paymentFlow.typeStringType of payment flowYesValues Allowed =[SUBSCRIPTION_SETUP]
paymentFlow.merchantSubscriptionIdStringUnique merchant reference subscription ID – used for subscription statusYes
paymentFlow.authWorkflowTypeStringType of setup workflowYesSubscription auth type.
Values:
● PENNY_DROP
● TRANSACTION
paymentFlow.amountTypeStringNature of redemption amountYesPossible Values :
● FIXED
● VARIABLE
paymentFlow.maxAmountLongMax amount upto which redemptions will be allowedYes
paymentFlow.frequencyStringSubscription frequencyYesPossible Values :
● DAILY
● WEEKLY
● MONTHLY
● YEARLY
● FORTNIGHTLY
● BIMONTHLY
● ON_DEMAND
● QUARTERLY
● HALFYEARLY
paymentFlow.expireAtDateTime
Subscription cycle expiry. No operation allowed after subscription expires.
(in milliseconds)
NoDefault Value : 30 years
paymentFlow.paymentModeObjectPayment mode details for setup.YesPossible Values :
{
    “type”: “UPI_INTENT”,
    “targetApp”: “com.phonepe.app”
}

{
    “type”: “UPI_COLLECT”,
    “details”: {
        “type”: “VPA”,
        “vpa”: “1234567890@ybl”
    }
}
paymentFlow.paymentMode.targetAppStringTarget app for intent payment mode.YesAndroid – Package Name of the UPI app

iOS – Static Values like PHONEPE / GPAY / PAYTM
deviceContext.deviceOSStringThe type of device OSYes
Possible values
● ANDROID
● IOS
metaInfo.udf1StringUser defines fields propagated in status check & callbacksNoDefault 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 NameDescription
orderIdPhonePe reference order ID
stateOrder state
intentUrlIntent 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 NameDescription
orderIdPhonePe reference order ID
stateOrder state