Recurring Flow FAQs

FAQs on Create User Subscription API

1. In the Create User Subscription API, How should the recurring count be calculated?

The recurring count can be considered in the following way:
For a time span of 1 year:

• In case of DAILY frequency: Recurring count will be 365.
• In case of MONTHLY frequency: Recurring count will be 12.
• In case of QUARTERLY frequency: Recurring count will be 4.
• In case of HALFYEARLY frequency: Recurring count will be 2.
• In case of YEARLY frequency: Recurring count will be 1.

For a time span of 2 years:

• In case of DAILY frequency: Recurring count will be 2 * 365 = 730.
• In case of MONTHLY frequency: Recurring count will be 2 * 12 = 24.
• In case of QUARTERLY frequency: Recurring count will be 8.
• In case of HALFYEARLY frequency: Recurring count will be 4.
• In case of YEARLY frequency: Recurring count will be 2 * 1 = 2.

For ON_DEMAND frequency,
The recurringCount parameter value can be anything in-between 1 to 30.
For instance:

• If the value is passed as 1 then it is valid for 1 year.
• If the value is passed as 2 then it is valid for 2 years and so on.

2. In the Create User Subscription API, whether the amount parameter mandatory in the case of autoWorkflowtype is PENNY_DROP ?

Yes, The amount parameter is mandatory for both the autoWorkflowtype: PENNY_DROP or TRANSACTION. The amount value will be the maximum amount that can be debited during the subscription cycle.

3. In the Create User Subscription API, is it mandatory to pass the merchantUserId? What is the use of the merchantUserId parameter?

Yes, it is the mandatory parameter. merchantUserId parameter will be used in the following APIs:

• To fetch all the subscriptions of the particular customer using Fetch All Subscriptions API.
• To cancel the subscription permanently for a particular customer using the Cancel Subscription API.

4. In the Create User Subscription API, how does the autoWorkFlowType parameter work when set to PENNY_DROP or TRANSACTION?

• PENNY_DROP is used for the verification of the bank account while setting up the mandate. When set to PENNY_DROP, Rs: 1 or 2 will be debited and credited back to the same account.
• TRANSACTION is used to debit the actual subscription amount. When set to TRANSACTION, the actual subscription amount will be debited from the customer’s account while setting up the mandate.

5. In the Create User Subscription API, do I need to set FIXED or VARIABLE values in amountType?

• When amountType is set to FIXED, the amount parameter value cannot be changed and will remain the same throughout the subscription cycle.
• When amountType is set to VARIABLE, the amount parameter value should be the maximum possible amount of the subscription throughout the subscription cycle. For instance, If merchants have subscriptions for Rs: 299, Rs: 399, and Rs:599, then merchants should pass the maximum amount which is Rs.599/- [59900 in paise].

6. In the Create User Subscription API response, how are the isSupportedUser and isSupportedApp validated? What is it used for?

• isSupportedUser is validated based on the mobileNumber parameter. Hence it is good practice to pass the mobile number parameter in the request payload of the Create User Subscription API. Note: PhonePe internally checks whether the passed mobile number has been linked with any of the Recurring supported UPI bank accounts. If merchants don’t pass mobileNumber, then isSupportedUser will always be returned as FALSE.
• isSupportedApp is validated based on the phonePeVersionCode parameter value.

Important Note

• Make sure that the latest PhonePe app is installed on the android device.
• PhonePeVersionCode should be greater than 400893 to support the Recurring payments flow.
• If the mobile number parameter is not passed then the isSupportedUser parameter will be always FALSE.
• It is a good practice to proceed with the Subscription only when the isSupportedApp and isSupportedUser values are TRUE in order to give the best user experience.

7. What is “ ON_DEMAND” frequency?

For “ ON_DEMAND” frequency, the recurringCount parameter value can be anything in-between 1 to 30 (in years).
For instance: If the value is passed as 1 then it means for 1 year.
If the value is passed as 2 then it means for 2 years and so on.

8. What would be the difference between “YEARLY” frequency and “ ON_DEMAND” frequency?

For ‘YEARLY’ frequency,

• When set to recurringCount value as 10, then debit will happen every year only once or twice for the next 10 years. For instance: Within consecutive years (ie. 2 years), Merchants can debit a maximum of thrice, but within a year Merchants can debit only twice.
• Recurring INIT API can be triggered 24 / 48 hours before the due date.

For ‘ ON_DEMAND’ frequency,

• When set to recurringCount value as 10, then there is no limit for the debit in this specific duration of 10 years. Merchants can debit maximum of 20 redemptions in rolling 24 hours until and unless cumulative redeemed sum is upto 1 lakh.
• Mandatorily Recurring INIT API should be triggered 24 hours before the due date.

Important Note: In case if Merchants try calling debit multiple times than the allowed, then the response SUBSCRIPTION_RECURRENCE_LIMIT_BREACHED will be received. This same is applicable for other frequencies except for DAILY. For DAILY frequency, merchants can debit only once.

9. What is the minimum amount for which mandate can be setup using the TRANSACTION as authWorkFlowType?

PhonePe supports mandate setup with a minimum amount of Rs. 1.

10. What is the maximum amount limit we can debit in a day? Is this 15K per transaction or for the entire day?

For subscription setup, max amount is 5-15K (depends on the bank as per the RBI/NPCI guidelines). So a single redemption can’t be more than that amount.

FAQs on Submit Auth API

1. How to support Open Intent UPI AutoPay solution?

• Create User Subscription API: In the request payload, the deviceContext parameter is not required. Also in the response, Merchants need not rely on the isSupportedApp and isSupportedUser parameters.
  Note: This will apply only to the PhonePe app and not to other UPI apps.
• Submit Auth Request API: In the request payload, you need to pass the value of the paymentInstrument.type parameter as “UPI_INTENT” and an additional parameter named “targetApp” where the value should
  • [In Android] package name of the UPI app selected
  • [In iOS] Static Values provided in the document.
    Refer here for the details.

FAQs on Recurring INIT API

1. In the request payload of the Recurring INIT API, What is the use of the autoDebit parameter?

• When autoDebit is set to TRUE, PhonePe internally will make the Recurring Debit Execute API in order to debit the amount from the customer’s account.
• When autoDebit is set to FALSE, merchants need to explicitly call Recurring Debit Execute API in order to debit the amount from the customer’s account.

2. Is it mandatory to trigger Recurring INIT API 24 hours before the due date?

Yes, it is mandatory.
Important note: We do not recommend Merchants to trigger Recurring INIT API on flexible hours before the due date.

3. In Recurring INIT API, if the autoDebit is set as TRUE, when will the amount get debited from the customer’s account?

Initially, Recurring INIT API should be triggered 24 hours before the due date. If the autoDebit is set to TRUE, PhonePe will execute the Recurring Debit API after 24 hours. If the amount gets debited successfully, then PhonePe will send the server to server callback response to the Merchant’s Callback URL.

Important Note

If the debit fails in the first attempt by PhonePe, then PhonePe makes 3 attempts (In total including the first attempt) in an hour’s time. If all the 3 attempts fail, then the failure S2S callback response will be sent.

FAQs on Recurring Debit Execute API

1. How to handle multiple debits based on the recurring frequency values?

• For DAILY frequency, Merchants can debit only once.
• For MONTHLY frequency – Within consecutive months (Eg. 2 months), Merchants can debit a maximum of thrice, but within a month Merchants can debit only twice. In case if Merchants try calling multiple times then the response SUBSCRIPTION_RECURRENCE_LIMIT_BREACHED will be received. This same is applicable for other frequencies except DAILY.

2. Can we trigger multiple recurring debits in case of a failure in the previous attempt?

• In case if there is a failure response in the sync response, then Merchants can retry Recurring Debit. For instance, if Merchant gets response codes like 400 BAD_REQUEST, 401 AUTHORIZATION_FAILURE, then the Merchants can retry.
• If in case Merchants get a response with the state as ACCEPTED but followed by a failure server to server callback response, then Merchants cannot retry calling the Recurring Debit again. So, Merchants should trigger the Recurring INIT API followed by the Recurring Debit Execute API.

3. In the server to server callback response, which response parameters should the merchant consider to get the final status of the subscription transaction?

For Successful transactions

success == true and
data.transactionDetails.state == “COMPLETED” and
data.subscriptionDetails.state == “ACTIVE”

For Failure transactions:

success == true and
data.transactionDetails.state == “FAILED” and
data.subscriptionDetails.state == “FAILED”.

Important Note

There is no intermediate/pending state in the server to server callback response, But in case if you did not receive the callback response then you should call status APIs to get the actual response of the payment.

4. Can we get the intermediate/pending state in status APIs? On what basis should we consider a pending state and How to handle it?

Yes, you can get the pending response in the status APIs.

For pending transactions:

success == true and
data.subscriptionDetails.state == “CREATED”.

In case if you receive the state as ‘CREATED’, You should explicitly reconcile status APIs till it reaches the terminal status of the payment.

5. On what basis the Recurring Debit Execute should be called?

Once you trigger Recurring INIT API 24 hours before the due date, You need to wait for the S2S Callback response from the Recurring INIT API and once the callback response is received check for the following:

• state parameter value should be NOTIFIED.
• Observe the value of the validAfter parameter.

Based on the value of the validAfter parameter you should call the Recurring Debit Execute API.
Important Note: Execution has to be done in validAfter to ValidUpto window only.

FAQs on Subscription Cancel API

1. We also have an option where the customer can cancel the subscription using the PhonePe app. How will this cancellation be handled?

• Once the customer cancels the subscription using the PhonePe app. You will receive the cancellation server to server callback response to your merchant Callback URL.

Important Note

You need to share the Static Callback URL which needs to be configured with PhonePe in order to receive the server-to-server callback response for the cancellation using the PhonePe App. Refer to this link for more details.

FAQs on Refund API

1. How to handle the Refund API for Subscription?

Refund API – Refer here
Check Status API – Refer here

• If the refund has to be done for the initial Submit Auth Request transaction, then the originalTransactionId or providerReferenceId of Submit Auth Request has to be passed.
• If the refund has to be done for the Recurring Debit Request transaction, then the originalTransactionId or providerReferenceId of corresponding Recurring Debit Request has to be passed.

General FAQs

1. Is it mandatory to perform the checksum validation and the amount parameter mismatch in the server to server call back response? If Yes, On which APIs do I receive the call back response?

Yes, It is mandatory to handle the checksum validation and the amount parameter mismatch in the server to server callbacks in order to avoid fraudulent transactions.

Here is the list of APIs:

• Submit Auth Request API
• Recurring INIT API
• Recurring Debit Execute API
• Cancel Subscription API
• Revoke Subscription using PhonePe App

2. If the user deletes the account from the PSP app in which the mandate was set up, what will happen to that mandate, and whether the recurring debits will still happen on the same account?

When the user goes to delete the account, there will be a check whether there are active mandates on it. In that case, we do not allow the user to delete the bank account and prompt the user to delete first their mandate.

Important Note

You also receive server-to-server callback responses when the customer cancels the subscription using the PhonePe app. Refer to this link for more details.