Setup Subscription using API

This API is used to set up a subscription for a customer.

Environment

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

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	Order amount in paisa.	Yes	Min value = 100 paise
`expireAt`	DateTime	Order expiry in seconds. If not passed default value will be used.	No	Min Value = 300, Max Value = 3600
`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

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	Mandatory (Yes/No)	Description	Constraints
paymentFlow.type	String	Yes	Type of payment flow.	Valued Allowed = [SUBSCRIPTION_CHECKOUT]
paymentFlow.message	String	No	Message to be displayed to user on paypage	Allowed Characters = [ A-Za-z0-9+-_ ] Max Length = 128
paymentFlow.merchantUrls	Object	Yes	Object to store different merchant Urls
paymentFlow.merchantUrls.redirectUrl	String	Yes	Url where user will be redirected after success/failed payment.
paymentFlow.merchantUrls.cancelUrl	String	No	Url where user will be redirected after cancelled payment.
paymentFlow.subscriptionDetails	Object	Yes	subscription details
paymentFlow.subscriptionDetails.subscriptionType	String	Yes	RECURRING, ONE_TIME etc
paymentFlow.subscriptionDetails.merchantSubscriptionId	String	Yes	merchant subscription Id
paymentFlow.subscriptionDetails.authWorkflowType	String	Yes	TRANSACTION / PENNY DROP
paymentFlow.subscriptionDetails.amountType	String	Yes	FIXED/ VARIABLE
paymentFlow.subscriptionDetails.maxAmount	Long	Yes	max redemption amount. The amount must be in paisa. Max Limit: 1500000 paisa
paymentFlow.subscriptionDetails.frequency	String	Yes	Redemption Frequency. Supported values: • Daily • Weekly • Monthly • Bi-monthly • Fortnightly • Quaterly • Half-Yearly • Annual • On-Demand
paymentFlow.subscriptionDetails.expireAt	epoch	No	Subscription Expiry
paymentFlow.subscriptionDetails.productType	String	Yes	UPI_MANDATE

Sample Request

{
    "merchantOrderId": "{{merchantOrderId}}",
    "amount": 47900,
    "paymentFlow": {
        "type": "SUBSCRIPTION_CHECKOUT_SETUP",
        "message": "Payment message used for collect requests",
        "merchantUrls": {
            "redirectUrl": "www.google.com",
            "cancelRedirectUrl": "www.google.com"
        },
        "subscriptionDetails": {
            "subscriptionType": "RECURRING",
            "merchantSubscriptionId": "{{merchantSubId}}",
            "authWorkflowType": "TRANSACTION",
            "amountType": "FIXED",
            "maxAmount": 47900,
            "frequency": "ON_DEMAND",
	    "productType": "UPI_MANDATE",
            "expireAt": 1779689282000
        }
    },
    "expireAfter": 3000,
    "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"
    }
}

Response

Sample Response

{
    "orderId": "OMO123456789",
    "state": "PENDING",
    "expireAt": 1703756259307,     
    "redirectUrl": "../transact/pgv2?token=<token>" 
}

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.