Setup Subscription

This API allows you to simultaneously create a user subscription and set up its payment mandate.

API Endpoint

Environment	HTTP Method	API
Sandbox	`POST`	https://api-preprod.phonepe.com/apis/pg-sandbox/paylinks/v1/pay
Production	`POST`	https://api.phonepe.com/apis/pg/paylinks/v1/pay

Request

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

Sample Request for Transaction

{
  "merchantOrderId": "MO110222000493",
  "description": "some message",
  "currency": "INR",
  "amount": 47900,
  "expireAt": 2592000,
  "constraints": [
    {
      "type": "ACCOUNT",
      "accountNumber": "1234567890",
      "ifsc": "HDFC13434"
    }
  ],
  "paymentFlow": {
    "type": "SUBSCRIPTION_PAYLINK_SETUP",
    "customerDetails": {
      "name": "Nikhil",
      "phoneNumber": "+919845******",
      "email": "[email protected]"
    },
    "subscriptionDetails": {
      "subscriptionType": "RECURRING",
      "merchantSubscriptionId": "MS10022200000483",
      "authWorkflowType": "TRANSACTION",
      "amountType": "VARIABLE",
      "maxAmount": 47900,
      "productType": "UPI_MANDATE",
      "frequency": "ON_DEMAND",
      "expireAt": 2889689282000
    },
    "metaInfo": {
      "udf1": "string",
      "udf2": "string",
      "udf3": "string",
      "udf4": "string",
      "udf5": "string",
      "udf6": "string",
      "udf7": "string",
      "udf8": "string",
      "udf9": "string",
      "udf10": "string",
      "udf11": "string",
      "udf12": "string",
      "udf13": "string",
      "udf14": "string",
      "udf15": "string"
    }
  }
}

Sample Request for Penny drop

{
  "merchantOrderId": "MO11022210010493",
  "description": "some message",
  "currency": "INR",
  "amount": 200,
  "expireAt": 2592000,
  "constraints": [
    {
      "type": "ACCOUNT",
      "accountNumber": "1234567890",
      "ifsc": "HDFC13434"
    }
  ],
  "paymentFlow": {
    "type": "SUBSCRIPTION_PAYLINK_SETUP",
    "customerDetails": {
      "name": "Nikhil",
      "phoneNumber": "+919845******",
      "email": "[email protected]"
    },
    "subscriptionDetails": {
      "subscriptionType": "RECURRING",
      "merchantSubscriptionId": "MS100120483",
      "authWorkflowType": "PENNY_DROP",
      "amountType": "VARIABLE",
      "maxAmount": 47900,
      "productType": "UPI_MANDATE",
      "frequency": "ON_DEMAND",
      "expireAt": 2889689282000
    },
    "metaInfo": {
      "udf1": "string",
      "udf2": "string",
      "udf3": "string",
      "udf4": "string",
      "udf5": "string",
      "udf6": "string",
      "udf7": "string",
      "udf8": "string",
      "udf9": "string",
      "udf10": "string",
      "udf11": "string",
      "udf12": "string",
      "udf13": "string",
      "udf14": "string",
      "udf15": "string"
    }
  }
}

Request Parameters

Parameter Name	Data Type	Description	Mandatory	Constraints
`merchantOrderId`	String	Unique orderId generated by the merchant to track the transactions.	Yes	• Max Length: 63 characters. • Only Alphanumeric characters, underscore “_” and hyphen “-“ are allowed.
`description`	String	A brief description of what the payment is for, and this message will be shown in the checkout page for your customers.	No	max size 150 characters
`currency`	Sting	Represents the currency of the subscription amount (e.g., INR, USD).	Yes
`amount`	Long	Transaction order amount in paise. This value is used to set up the mandate based on the selected 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	epoch	Specifies the timestamp when the payment link will expire.	Yes
`paymentFlow`	Object	Contains additional details required to process the selected payment flow.	Yes
`paymentFlow.type`	String	Specifies the type of payment flow to be executed.	Yes	Allowed value: “SUBSCRIPTION_CHECKOUT_SETUP”
`subscriptionDetails`	Object	Contains all configuration details related to the subscription setup.	Yes
`subscriptionDetails.subscriptionType`	String	Specifies the type of subscription being created.	Yes	Allowed value: “RECURRING”
`subscriptionDetails.merchantSubscriptionId`	String	Unique ID for the subscription, generated by the merchant.	Yes	Max Length: 63 characters.
`subscriptionDetails.authWorkflowType`	String	Specifies the setup flow to be used (e.g., TRANSACTION or PENNY_DROP).	Yes	Allowed values: “TRANSACTION” or “PENNY DROP”
`subscriptionDetails.amountType`	String	Defines how the debit amount is determined throughout the subscription lifecycle.	Yes	Allowed values: “FIXED” or “VARIABLE”
`subscriptionDetails.maxAmount`	Long	Maximum amount that can be debited during the subscription cycle. Value should be in paise.	Yes	Max Limit: 1500000 paisa(i.e., ₹15,000)
`paymentFlow.subscriptionDetails.frequency`	String	Specifies how often the subscription amount will be debited.	Yes	Allowed values: • DAILY • WEEKLY • MONTHLY • FORTNIGHTLY • BIMONTHLY • QUARTERLY • HALFYEARLY • YEARLY • ON_DEMAND
`subscriptionDetails.productType`	String	Specifies the type of mandate or payment instrument being used.	Yes	Allowed value: UPI_MANDATE
`subscriptionDetails.expireAt`	epoch	Defines the expiry time of the subscription.	No	Max value: 30 Years.
`metaInfo`	Object	Additional information defined by merchant. This data is returned in both status and callback responses.	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.

Response

Sample Response

{
    "orderId": "OMO2606111408417110362689BW",
    "state": "ACTIVE",
    "paylinkUrl": "https://stg.phon.pe/t5oy9p6k",
    "expireAt": 1783759121079
}

Response Parameters

Field Name	Data Type	Description
`orderId`	String	Unique internal orderId generated by PhonePe Payment Gateway.
`state`	String	State of the order created, expected value is Active.
`expiryAt`	Long	Expiry time of the order represented as an epoch timestamp.
`paylinkUrl`	String	The URL where the customer can access the payment page and complete the transaction.