Setup Subscription using API

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

Environment

Request

The metaInfo object contains additional parameters, which are explained in the table below.

The paymentFlow object contains additional parameters, which are explained in the table below.

{
    "merchantOrderId": "{{merchantOrderId}}",
    "amount": 47900,
    "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_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
}

Response

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

What’s Next?

Once you have setup the subscription, next step is to:

Subscription Status

In this step, you can verify the current status of the subscription.

For complete details, refer to the Subscription Status.

Redemption Notify

In this step, you should call Redemption Notify API from your backend. This API will initiate a notification to your customer informing them that their debit is scheduled after 24 hours.

For complete details, refer to the Redemption Notify.

Redemption Execute

The Redemption Execute API is to directly debit the required payment from a user’s bank account, thereby initiating and completing the actual financial transaction. This API should be called from the backend only if it is Merchant controlled debit.

For complete details, refer to the Redemption Execute.

Verifying Payment Response

In a subscription system, it’s important to know whether a payment was successful, failed, or still pending.

PhonePe supports this with automated callbacks for two key events:

• Subscription Callbacks
  Sent when a new subscription is created. These confirm if the customer’s first payment was successful or not, helping you handle activation or failure from the start.
• Redemption Callbacks
  Sent for ongoing auto debits. These share the status of each recurring payment and provide individual transaction details, which are useful for retries and reconciliation.

By following these steps, from setting up the subscription and notifying the user to executing the redemption and managing the lifecycle, you have successfully integrated the recurring payment flow. Your system is now ready to process automated transactions efficiently.