Subscription Setup

The Subscription Setup process allows you to initiate a subscription. By calling the setup() method, you can create a subscription with either UPI_INTENT or UPI_COLLECT payment methods. The setup requires specific parameters such as the order ID, subscription ID, amount, frequency, and expiration details. The response from the setup contains essential information like the order state and intent URL for further payment processing.

Setting Up Subscription with UPI_INTENT

The setup() method is used to initiate the subscription setup with UPI_INTENT. Use the builder PgPaymentRequest.build_subscription_setup_upi_intent() to start the process.

Required Parameters for UPI_INTENT Setup

Attribute	Data Type	Mandatory	Description	Default Value
`merchant_order_id`	String	Yes	Unique order ID generated by the merchant.
`merchant_subscription_id`	String	Yes	Unique subscription ID generated by the merchant.
`amount`	Int	Yes	Amount in Paisa (FULL auth – first debit amount, PENNY auth – 200).
`order_expire_at`	Int	No	Epoch timestamp; the order will automatically fail if not completed within the given time (default is 10 minutes).	10 mins
`auth_workflow_type`	AuthWorkflowType	Yes	Type of setup workflow (TRANSACTION or PENNY_DROP)
`amount_type`	AmountType	Yes	Redemption amount type (FIXED or VARIABLE).
`max_amount`	Int	Yes	Maximum amount up to which redemptions will be allowed.
`frequency`	Frequency	Yes	Subscription frequency (DAILY, WEEKLY, MONTHLY, etc.)
`subscription_expire_at`	Int	No	Subscription expiration timestamp (No operations allowed after expiry, default is 30 years).
`target_app`	String	No	Target app for intent payment mode: • Android – package name • iOS – PHONEPE / GPAY / PAYTM
`meta_info`	MetaInfo	No	User-defined fields for status checks and callbacks

Example Code for UPI_INTENT Setup

Code Reference

import uuid
import time
from phonepe.sdk.pg.env import Env
from phonepe.sdk.pg.subscription.v2.subscription_client import SubscriptionClient
from phonepe.sdk.pg.subscription.v2.models.request.amount_type import AmountType
from phonepe.sdk.pg.subscription.v2.models.request.auth_workflow_type import AuthWorkflowType
from phonepe.sdk.pg.subscription.v2.models.request.frequency import Frequency
from phonepe.sdk.pg.common.models.request.pg_payment_request import PgPaymentRequest
 
client_id = "<clientId>"
client_secret = "<clientSecret>"
client_version = <clientVersion>  # insert your client version here
env = Env.SANDBOX  # change to Env.PRODUCTION when you go live
 
subscription_client = SubscriptionClient.get_instance(client_id=client_id,
                                                              client_secret=client_secret,
                                                              client_version=client_version,
                                                              env=env)
merchant_order_id = str(uuid.uuid4())
merchant_subscription_id = str(uuid.uuid4())
amount = 100
auth_workflow_type = AuthWorkflowType.TRANSACTION
amount_type = AmountType.FIXED
frequency = Frequency.ON_DEMAND
max_amount = 100
device_os = "IOS"
merchant_callback_scheme = ""
target_app = "PHONEPE"
subscription_expire_at = int(time.time() * 1000) + 1000000
order_expire_at = int(time.time() * 1000) + 1000000
 
setup_request = PgPaymentRequest.build_subscription_setup_upi_intent(
    merchant_order_id=merchant_order_id,
    merchant_subscription_id=merchant_subscription_id,
    amount=amount,
    device_os=device_os,
    merchant_callback_scheme=merchant_callback_scheme,
    target_app=target_app,
    auth_workflow_type=auth_workflow_type,
    subscription_expire_at=subscription_expire_at,
    amount_type=amount_type,
    frequency=frequency,
    order_expire_at=order_expire_at,
    max_amount=max_amount
)
 
setup_response = subscription_client.setup(setup_request)
intent_url = setup_response.intent_url

Return Values for UPI_INTENT

The function returns a PgPaymentResponse object with the following properties:

Parameter Name	Data Type	Description
`order_id`	String	Unique order ID generated by PhonePe.
`state`	String	State of the order. Initially it will be PENDING.
`intent_url`	String	Intent url according to the targetApp mentioned in the request.

Setting Up Subscription with UPI_COLLECT

The setup() method can also initiate the subscription setup with UPI_COLLECT. Use the builder PgPaymentRequest.build_subscription_setup_upi_collect() to begin.

Attribute	Data Type	Mandatory	Description	Default Value
`merchant_order_id`	String	Yes	Unique order ID generated by the merchant.
`merchant_subscription_id`	String	Yes	Unique subscription ID generated by the merchant.
`amount`	Int	Yes	Amount in Paisa (FULL auth – first debit amount, PENNY auth – 200).
`order_expire_at`	Int	No	Epoch timestamp; the order will automatically fail if not completed within the given time (default is 10 minutes).	10 mins
`auth_workflow_type`	AuthWorkflowType	Yes	Type of setup workflow (TRANSACTION or PENNY_DROP)
`amount_type`	AmountType	Yes	Redemption amount type (FIXED or VARIABLE).
`max_amount`	Int	Yes	Maximum amount up to which redemptions will be allowed.
`frequency`	Frequency	Yes	Subscription frequency (DAILY, WEEKLY, MONTHLY, etc.)
`subscription_expire_at`	Int	No	Subscription expiration timestamp (No operations allowed after expiry, default is 30 years).
`target_app`	String	No	Target app for intent payment mode: • Android – package name • iOS – PHONEPE / GPAY / PAYTM
`meta_info`	MetaInfo	No	User-defined fields for status checks and callbacks.
`vpa`	String	Yes	Virtual Payment Address (VPA) for which the collect request will be raised.

Example Code for UPI_COLLECT Setup

Code Reference

import uuid
import time
from phonepe.sdk.pg.env import Env
from phonepe.sdk.pg.subscription.v2.subscription_client import SubscriptionClient
from phonepe.sdk.pg.subscription.v2.models.request.amount_type import AmountType
from phonepe.sdk.pg.subscription.v2.models.request.auth_workflow_type import AuthWorkflowType
from phonepe.sdk.pg.subscription.v2.models.request.frequency import Frequency
from phonepe.sdk.pg.common.models.request.pg_payment_request import PgPaymentRequest
 
 
client_id = ""
client_secret = ""
client_version = 1  # insert your client version here
env = Env.SANDBOX  # change to Env.PRODUCTION when you go live
 
subscription_client = SubscriptionClient.get_instance(client_id=client_id,
                                                              client_secret=client_secret,
                                                              client_version=client_version,
                                                              env=env)
merchant_order_id = str(uuid.uuid4())
merchant_subscription_id = str(uuid.uuid4())
amount = 200  # In paisa
auth_workflow_type = AuthWorkflowType.TRANSACTION
amount_type = AmountType.FIXED
frequency = Frequency.ON_DEMAND
vpa = ""
max_amount = 200
subscription_expire_at = int(time.time() * 1000) + 1000000  # Not mandatory (default 30 years)
order_expire_at = int(time.time() * 1000) + 1000000 # Not mandatory (default 10 mins)
 
setup_request = PgPaymentRequest.build_subscription_setup_upi_collect(
    merchant_order_id=merchant_order_id,
    merchant_subscription_id=merchant_subscription_id,
    amount=amount,
    auth_workflow_type=auth_workflow_type,
    subscription_expire_at=subscription_expire_at,
    amount_type=amount_type,
    frequency=frequency,
    order_expire_at=order_expire_at,
    max_amount=max_amount,
    vpa=vpa,
)
 
setup_response = subscription_client.setup(setup_request)

Return Values for UPI_COLLECT

The function will raise a collect request to the provided VPA.

The function returns a PgPaymentResponse object with the following properties:

Parameter Name	Data Type	Description
`order_id`	String	Unique order ID generated by PhonePe.
`state`	String	State of the order. Initially it will be PENDING.

What’s Next ?

After setting up the subscription, the next step is to check the Order Status. Head over to the next section to learn how to check the status of an order.