Getting Started With UPI AutoPay

Overview

UPI AutoPay allows merchants to collect recurring or future payments after a customer approves a mandate through their UPI app.

A mandate defines the authorised amount rule, validity period, and recurrence settings. Creating a mandate does not mean that the customer has approved it or that a payment has been successfully collected.

With WowPe's UPI AutoPay APIs, you can create mandates, collect customer approvals, configure recurring payment schedules, initiate debit notifications, and track payment outcomes.

Authentication

All UPI AutoPay API requests require merchant credentials obtained from the WowPe Dashboard.

Include the following credentials in the JSON request body of every API request:

Parameter	Type	Mandatory	Description
`clientId`	String	Yes	Merchant Client ID provided in the WowPe Dashboard.
`secretKey`	String	Yes	Merchant Secret Key provided in the WowPe Dashboard.

Request Header

Header	Value
`Content-Type`	`application/json`

All API endpoints use the POST method and accept JSON request bodies.

Important: Make API requests from your backend server. Keep your secretKey confidential and never expose it in frontend code, mobile application bundles, screenshots, source control, or logs.

The customer must enter their UPI PIN only within their UPI application.

Common Request Format

The following example illustrates the request format for retrieving mandate details:

curl --request POST '{{BASE_URL}}/mandate-details' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientId": "YOUR_CLIENT_ID",
    "secretKey": "YOUR_SECRET_KEY",
    "orderId": "ORD10001"
  }'

Replace {{BASE_URL}} with the applicable WowPe API environment URL and use your merchant credentials securely.

Choose Your Collection Flow

UPI AutoPay supports different ways to manage recurring and future debit collections. Choose the collection flow based on your business requirements.

1. Automatic Plan

Configure the first debit, introductory debit, and recurring debit details within the mandate-create request using the optional plan object.

Once the customer approves the mandate, the configured debit plan is managed automatically.

2. Standalone Schedule

Create a mandate without configuring an automatic plan. Once the customer approves the mandate, use the mandate-schedule API to create a recurring payment schedule.

Notifications and scheduled debits are then managed automatically.

3. Individually Scheduled Debit

Create a mandate without configuring an automatic plan. Once the customer approves it, use the mandate-notify API to submit a pre-debit notification for an individual debit.

The debit is then processed automatically at the specified executionDateTime.

4. Initial Debit at Mandate Approval

The mandate-execute API also supports an initial debit associated with customer approval.

This flow is subject to the eligibility rules supported by the bank/backend. Refer to the Execute Debit API documentation for the applicable request format.

Important: Choose only one collection mechanism for each charge. Do not manually initiate a debit that is already configured as plan.firstDebitAmount, or submit another execute request for a debit that is already pending automatic execution.

Integration Flow

Follow these steps to integrate UPI AutoPay:

Validate VPA (Optional): Use the mandate-validate-vpa API to validate the customer's UPI ID and retrieve the account holder's name.
Create Mandate: Call mandate-create to create a mandate and obtain the UPI approval link.
Collect Customer Approval: Present the returned UPI link to the customer as a QR code or launch it as a mobile intent.
Verify Mandate Status: Use mandate-details to check whether the customer has approved the mandate. Proceed with collections only after confirming mandateStatus: "Active".
Configure Collections: Follow the selected collection flow — Automatic Plan, Standalone Schedule, or Individually Scheduled Debit.
Track Payment Status: Use the relevant notification and debit status APIs to monitor the outcome of each operation.
Revoke Mandate (If Required): Use mandate-modify to submit a mandate revocation request and track its status.

Understanding API Status Codes

The statusCode field indicates the outcome of the requested API operation. It does not necessarily indicate whether a payment has been completed.

`statusCode`	Meaning
`0`	Operation failed. Check the `message` and applicable status fields.
`1`	Operation succeeded. Check the relevant business status to determine the actual outcome.
`2`	Operation is pending. Use the relevant status API to track the outcome.

Business Status Fields

Different status fields represent different stages of the mandate and payment lifecycle.

Status Field	Possible Values	Description
`mandateStatus`	`Created`, `Active`, `Paused`, `Revoked`, `Expired`, `Completed`, `Failed`	Indicates the current mandate lifecycle status.
`notifyStatus`	`NotSent`, `Pending`, `Success`, `Failed`	Indicates the status of the pre-debit notification.
`txnStatus`	`NotInitiated`, `Pending`, `Success`, `Failed`	Indicates the debit transaction status.
`planStatus`	`Waiting`, `Started`, `PartlyFailed`, `Cancelled`	Indicates the progress of an automatic debit plan.
`scheduleStatus`	`Active`, `Stopped`, `Completed`	Indicates the status of a recurring payment schedule.

Important: An active mandate does not mean that a payment has been collected. Similarly, successful pre-debit notification does not confirm a successful debit. Treat a payment as successful only after confirming txnStatus: "Success" through the relevant status API.

Identifiers, Amounts, and Date-Time Formats

Identifiers

Provide a unique orderId for every new mandate.
Provide a unique debitId for every new merchant-initiated debit.
Store the identifiers returned by the APIs for future status checks and reconciliation.
Automatic plans and schedules may return debit identifiers such as firstDebitId, introDebitId, and lastDebitId. Use the returned identifiers when checking debit status.

Amounts

All amounts are in INR.
Amounts support up to two decimal places.
Request amounts should be passed as JSON numbers.
Response amounts may be returned as decimal strings, such as "99.00".
Preserve monetary precision when processing amounts.
Treat transaction references such as rrn as strings.

Date and Time

The API uses Indian Standard Time (IST).
Request date-time values follow the format yyyy-MM-ddTHH:mm:ss.
Validity dates are represented at midnight.
Response date-time fields may use different formats, including date-only values, date-times with a space separator, and date-times with an explicit +05:30 offset.

Preserve the returned date-time values and interpret them consistently.

Pre-debit Notification Windows

The documented notification and execution windows are:

API / Configuration	Time Window
`mandate-notify`	Execution time must be 24–72 hours from the request.
Schedule notification lead time	25–71 hours.
Default schedule notification lead time	26 hours.

Ensure that the requested execution time falls within the mandate's validity period.

Handling Pending Responses and Retries

A pending response or request timeout does not necessarily mean that the operation failed.

Follow these guidelines:

If an API request times out or returns a pending response, check the existing operation using the relevant status API before submitting another request.
Do not generate a new ID and automatically resubmit a mandate or debit when the original outcome is unknown.
One pre-debit notification is associated with one debit.
For a confirmed failed debit, the documented flow calls for a fresh mandate-notify request with a new debitId.
The system may use retry identifiers with suffixes such as -R1, -R2, and so on. Use the identifiers returned by the API rather than generating retry IDs yourself.

Always verify the existing transaction outcome before attempting another collection.

What's Next

Explore the individual API references to understand the request parameters, sample requests, responses, and integration steps:

Validate VPA – Validate a customer's UPI ID.
Create Mandate – Create a mandate and generate the customer approval link.
Mandate Details – Retrieve mandate information and status.
Pre-debit Notify – Submit a pre-debit notification.
Notify Status – Check notification status.
Execute Debit – Submit an eligible initial debit or supported execution request.
Execute Status – Check the outcome of a debit transaction.
Create Schedule – Configure a recurring payment schedule.
Schedule Status – Retrieve schedule information and progress.
Stop Schedule – Stop an existing recurring payment schedule.
Revoke Mandate – Submit a mandate revocation request.
Request Status – Track the status of an API request.