{"title":"UPI Autopay for API only","category":"default","creationDate":1776961628,"content":"

With UPI Autopay, shoppers can link their bank account to a mobile app, allowing them to set up recurring payments via instant bank transfer. Shoppers can use one of a number of apps built by participating banks or third party app partners that support UPI Autopay. Refer to this comprehensive list<\/a>.<\/p>\n

Requirements<\/h2>\n\n\n\n\n\n\n
Requirement<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
Integration type<\/strong><\/td>\nMake sure that you have an existing API-only integration<\/a>.<\/td>\n<\/tr>\n
Setup steps<\/strong><\/td>\nTo design your front-end, follow the recommended design guidelines<\/a> to provide an optimal checkout experience to your shoppers on UPI Autopay.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
\n

Special characters are not allowed by the acquirer.<\/strong><\/p>\n

All merchant-defined values, such as for merchantReference<\/code>, shopperReference<\/code>, and remarks<\/code>, that you send to the various applicable API requests (like \/payments<\/a> and \/payments\/{paymentPspReference}\/refunds<\/a> must be alphanumeric.<\/p>\n<\/div><\/div>\n

Set up a billing plan<\/h2>\n

To initiate a billing plan for a shopper, you need to get shopper approval to create an Autopay mandate in their UPI app and store their payment details when the mandate is approved successfully . The UPI payment service provider and the issuing bank use this mandate to track the shopper's billing plan. This setup also enables the shopper to cancel the mandate directly from their UPI app.<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Field<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
paymentMethod.type<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nType of UPI flow. Possible values: upi_collect<\/strong><\/span>, upi_intent<\/strong><\/span>, and upi_qr<\/strong><\/span>.<\/td>\n<\/tr>\n
paymentMethod.virtualPaymentAddress<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nRequired for upi_collect<\/strong><\/span>. Virtual Payment Address. A unique identifier used to let UPI connect to the shopper's bank account.<\/td>\n<\/tr>\n
paymentMethod.appId<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nRequired for upi_intent<\/strong><\/span>. The ID of the Third Party Application that is used in intent flow. Possible values: gpay<\/strong><\/span>, phonepe<\/strong><\/span>, bhim<\/strong><\/span>, and paytm<\/strong><\/span>.If omitted or set to null<\/strong><\/span>, response returns a generic Android app drawer link (not supported on iOS).<\/td>\n<\/tr>\n
storePaymentMethod<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nSet to true<\/strong><\/span> to store shopper's payment details.<\/td>\n<\/tr>\n
shopperInteraction<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nSet to Ecommerce<\/strong><\/span>.<\/td>\n<\/tr>\n
recurringProcessingModel<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nSet to Subscription<\/strong><\/span> or UnscheduledCardOnFile<\/strong><\/span>.<\/td>\n<\/tr>\n
shopperReference<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nThe shopper reference associated with the billing plan (minimum length three characters).<\/td>\n<\/tr>\n
reference<\/code><\/td>\n<\/td>\nOptional, must be alphanumeric when included. No space and special characters allowed.<\/td>\n<\/tr>\n
amount.value<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nThe first authorisation amount to charge the shopper in minor units. Note that this amount should be less than or equal to the mandate.amount<\/code> and the first authorisation on this amount happens automatically within 5 minutes of successful mandate registration. If there is no amount to be charged during the signup (in case of free trails, tokenising shopper payment details etc.,) refer to handling free trials<\/a> section<\/td>\n<\/tr>\n
amount.currency<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nSet to INR<\/strong><\/span>.<\/td>\n<\/tr>\n
mandate.amount<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nThe maximum amount the shopper will be charged per recurring debit in minor units. Must be more than or equal to amount.value<\/code>. The recurring charge does not need to go through authentication if the amount is less than or equal to INR 15,000.<\/td>\n<\/tr>\n
mandate.amountRule<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nPossible values: max<\/strong><\/span> and exact<\/strong><\/span>.
  • max<\/strong><\/span> - The shopper can be charged any amount between INR 1 to the amount in the amount.value<\/code> field.<\/li>
  • exact<\/strong><\/span> - The shopper can only be charged the amount in the amount.value<\/code> field.<\/li><\/ul><\/td>\n<\/tr>\n
mandate.frequency<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nThe frequency at which the shopper will be charged. Possible values: monthly<\/strong><\/span>, weekly<\/strong><\/span> and adhoc<\/strong><\/span>.Use adhoc<\/strong><\/span> if free trial or billing cycles differ.<\/td>\n<\/tr>\n
mandate.startsAt<\/code><\/td>\n<\/td>\nCurrent transaction date in YYYY-MM-DD<\/strong><\/span> format. Defaulted to the current date if not sent explicitly in the request.<\/td>\n<\/tr>\n
mandate.endsAt<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nEnd date of the billing plan, in YYYY-MM-DD<\/strong><\/span> format.<\/td>\n<\/tr>\n
mandate.remarks<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nLimited to 20 characters, spaces allowed, but no special characters. Displayed in the shopper's UPI app (on supported apps), under the Autopay<\/strong><\/span> section.<\/td>\n<\/tr>\n
mandate.billingAttemptsRule<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nRequired for monthly and weekly frequencies. Possible values: before<\/strong><\/span>, after<\/strong><\/span>, and on<\/strong><\/span>.
  • before<\/strong><\/span> - You can initiate the charge and retries anytime from the 1st day of the billing cycle to the mandate.billingDay<\/code>.<\/li>
  • after<\/strong><\/span> - You can initiate the charge and retries any time from the mandate.billingDay<\/code> to the end of billing cycle (for example end of the month for monthly frequency).<\/li>
  • on<\/strong><\/span> - You can initiate the charge and retries only on the mandate.billingDay<\/code>.<\/li><\/ul>This field does not apply to adhoc frequencies.<\/td>\n<\/tr>\n
mandate.billingDay<\/code><\/td>\n\"-white_check_mark-\"<\/td>\nRequired for monthly and weekly frequencies. The day of the billing cycle when the shopper will be charged.For monthly frequency: If mandate.billingDay<\/code> is 26, the shopper is charged on the 26th of every month. Valid values: 1\u201331.For weekly frequency: If mandate.billingDay<\/code> is 5, the shopper is charged every Friday. (1 = Monday, 2 = Tuesday, ..., 7 = Sunday). Valid values: 1\u20137. This field does not apply to adhoc frequencies.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n
\n
\n \n <\/tabs>\n <\/div>\n<\/div>\n\n

Webhooks for payment result<\/h3>\n

You can receive the mandate details as part of your standard webhooks. To do this:<\/p>\n

    \n
  1. In your Customer Area<\/a>, go to Developers<\/strong> > Webhooks<\/strong>.<\/li>\n
  2. Next to Standard webhook<\/strong>, select the edit webhook<\/strong> icon.<\/li>\n
  3. Under Additional Settings<\/strong>, select Include Mandate Details<\/strong>.<\/li>\n
  4. If you would like to receive additional UPI metadata like VPA, issuer handle and bank code, Under Additional Settings<\/strong>, select Include UPI Metadata<\/strong> (VPA, handle and issuer bank code).<\/li>\n
  5. Select Save Configuration<\/strong>.<\/li>\n<\/ol>\n

    Specific fields for UPI Autopay in the authorization webhook:<\/p>\n\n\n\n\n\n\n\n\n\n\n
    Field<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    mandate.mandateId<\/code><\/td>\nUnique Mandate Number for the mandate created by NPCI (also called UMN). Store this id for future use.<\/td>\n<\/tr>\n
    mandate.status<\/code><\/td>\nCurrent status of the mandate (for example active, or cancelled).<\/td>\n<\/tr>\n
    mandate.txVariant<\/code><\/td>\nTransaction variant used (upi_collect<\/strong><\/span> or upi_qr<\/strong><\/span>)<\/td>\n<\/tr>\n
    upi.vpa<\/code><\/td>\nShopper's Virtual Payment Address.<\/td>\n<\/tr>\n
    upi.handle<\/code><\/td>\nThird-party UPI app handle (for example okhdfc<\/strong><\/span>, or okicici<\/strong><\/span>).<\/td>\n<\/tr>\n
    upi.issuerBank<\/code><\/td>\nFirst four characters of the shopper's issuing bank IFSC code.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    Webhook for payment result:<\/p>\n\n\n\n\n\n\n
    eventCode<\/th>\nsuccess<\/th>\nDescription<\/th>\nAction to take<\/th>\n<\/tr>\n<\/thead>\n
    AUTHORISATION<\/td>\nfalse<\/td>\nThe transaction failed.<\/td>\nCancel the order and inform the shopper that the payment failed. Any amount debited will be refunded in 2\u20133 days.<\/td>\n<\/tr>\n
    AUTHORISATION<\/td>\ntrue<\/td>\nThe shopper successfully completed the payment and a mandate was created.<\/td>\nInform the shopper that the payment was successful and proceed with the order.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    \n <\/code-sample>\n<\/div>\n

    Make recurring payments<\/h2>\n

    For every subsequent payment in a billing plan, you need to:<\/p>\n

      \n
    1. Send a pre-debit notification.<\/li>\n
    2. Make the recurring payment.<\/li>\n<\/ol>\n
      \n

      As per the latest NPCI guidelines, you are required to perform any non-customer initiated transactions, such as Autopay pre-debit notifications and recurring transactions, during non-peak hours only, as outlined below for Indian Standard Time:<\/p>\n