Create Mandate

API Details

Parameter	Value
Method	`POST`
Endpoint	`/mandate-create`
Base URL	`{{BASE_URL}}`
Content-Type	`application/json`

Authentication

Include the following credentials in the JSON request body. These credentials are available in the WowPe Dashboard.

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

Request Header

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

Request Parameters

The following parameters are required or optional in addition to the authentication credentials.

Parameter	Type	Mandatory	Description
`orderId`	String	Yes	Unique merchant reference for the mandate.
`amount`	Number	Yes	Maximum or exact amount per debit, depending on `amountRule`.
`amountRule`	String	No	Amount rule. Accepted values: `MAX` or `EXACT`. Default: `MAX`.
`validityStart`	String (Date)	Yes	First valid date of the mandate. Must be today or a future date. Format: `yyyy-MM-ddT00:00:00`.
`validityEnd`	String (Date)	Yes	Last valid date of the mandate. Must be after `validityStart`.
`mandateName`	String	No	Name displayed to the customer in the UPI application.
`note`	String	No	Additional remarks for the mandate.
`purpose`	String	No	Purpose code. Default: `14`.
`recur`	String	No	Recurrence frequency. Default: `ASPRESENTED`.
`recurValue`	Number	No	Debit day based on the selected recurrence frequency.
`recurType`	String	No	Recurrence type: `ON`, `BEFORE`, or `AFTER`. Default: `ON`.
`minAmount`	Number	No	Minimum debit amount. Must be lower than `amount`.
`revocable`	String	No	Indicates whether the mandate is revocable. Accepted values: `Y` or `N`.
`plan`	Object	No	Configuration for automatic debit plans, including initial, introductory, and recurring debits.

Supported Recurrence Values

The recur parameter accepts the following values:

ASPRESENTED
ONETIME
DAILY
WEEKLY
FORTNIGHTLY
MONTHLY
BIMONTHLY
QUARTERLY
HALFYEARLY
YEARLY

Recurrence Configuration

Parameter	Type	Description
`recurValue`	Number	Debit day. For `WEEKLY`, the accepted range is 1–7; for `FORTNIGHTLY`, 1–16; and for `MONTHLY` and longer frequencies, 1–31.
`recurType`	String	Defines whether the debit occurs `ON`, `BEFORE`, or `AFTER` the specified `recurValue`.

Optional `plan` Object

The optional plan object allows you to configure automatic debit collections after the customer approves the mandate.

Parameter	Type	Description
`firstDebitAmount`	Number	Initial debit amount after mandate approval. `validityStart` must be the current date.
`introDebit.amount`	Number	Amount for a one-time introductory debit.
`introDebit.afterHours`	Number	Number of hours after approval for the introductory debit. Minimum: 24 hours. Alternatively, use `introDebit.at`.
`introDebit.at`	String (DateTime)	Fixed IST date-time for the introductory debit. Must be at least 24 hours and 10 minutes after approval.
`recurring.amount`	Number	Amount for each recurring debit.
`recurring.frequency`	String	Recurring frequency: `DAILY`, `WEEKLY`, `FORTNIGHTLY`, `MONTHLY`, `BIMONTHLY`, `QUARTERLY`, `HALFYEARLY`, or `YEARLY`.
`recurring.dayOfMonth`	Number	Day of the month for monthly and longer frequencies. Accepted range: 1–31; 1–28 is recommended.
`recurring.weekDay`	Number	Day of the week for weekly or fortnightly frequencies. Monday = 1 and Sunday = 7.
`recurring.time`	String	Recurring debit time in IST (`HH:mm`). Default: `10:00`.
`recurring.startFrom`	String	Determines when recurring debits begin: `AFTER_APPROVAL` or `AFTER_INTRO`. Default: `AFTER_INTRO` when an introductory debit is configured.
`recurring.startDate`	String (Date)	Fixed date for the first recurring debit, instead of using `dayOfMonth` or `weekDay`.
`recurring.endDate`	String (Date)	Last recurring debit date. Defaults to `validityEnd`.
`recurring.notifyBeforeHours`	Number	Notification lead time in hours. Accepted range: 25–71. Default: 26.

Sample Request

Example A: Create Mandate With Automatic Plan

This example creates a mandate with an initial debit, an introductory debit, and monthly recurring debits.

{
  "clientId": "YOUR_CLIENT_ID",
  "secretKey": "YOUR_SECRET_KEY",
  "orderId": "ORD10001",
  "amount": 99,
  "amountRule": "MAX",
  "validityStart": "2026-11-01T00:00:00",
  "validityEnd": "2027-10-31T00:00:00",
  "mandateName": "Monthly plan",
  "note": "Subscription",
  "recur": "ASPRESENTED",
  "plan": {
    "firstDebitAmount": 1,
    "introDebit": {
      "amount": 99,
      "afterHours": 24
    },
    "recurring": {
      "amount": 99,
      "frequency": "MONTHLY",
      "dayOfMonth": 3,
      "time": "10:00",
      "startFrom": "AFTER_INTRO"
    }
  }
}

Example B: Create Mandate Without Automatic Plan

Use this request when you intend to manage individual debits or create a standalone schedule separately.

{
  "clientId": "YOUR_CLIENT_ID",
  "secretKey": "YOUR_SECRET_KEY",
  "orderId": "ORDMANUAL01",
  "amount": 99,
  "amountRule": "MAX",
  "validityStart": "2026-11-01T00:00:00",
  "validityEnd": "2027-10-31T00:00:00",
  "mandateName": "Individual collections",
  "recur": "ASPRESENTED"
}

cURL Request

Save the applicable JSON request body as mandate-create.json and supply your credentials securely on your server.

curl --request POST '{{BASE_URL}}/mandate-create' \
  --header 'Content-Type: application/json' \
  --data-binary '@mandate-create.json'

Replace {{BASE_URL}} with the applicable WowPe API environment URL.

Sample Response

Success Response

The following is an illustrative response for Example A.

{
  "statusCode": 1,
  "message": "Success Plan saved: it starts automatically when the payer approves.",
  "orderId": "ORD10001",
  "mandateRef": "MD261101101530123456",
  "upiurl": "upi://mandate?pa=merchant@yesbank&pn=Merchant&mn=Monthly%20plan&validitystart=01112026&validityend=31102027&am=99.00&amrule=MAX&recur=ASPRESENTED&tr=MD261101101530123456&cu=INR&mc=5411&orgid=000000&mode=13&purpose=14&txnType=CREATE"
}

Response Parameters

Parameter	Type	Description
`statusCode`	Number	Indicates the API operation status. `0` = Failed, `1` = Succeeded, `2` = Pending.
`message`	String	Provides the response message, including the automatic plan creation status.
`orderId`	String	Merchant reference submitted in the request.
`mandateRef`	String	Unique mandate reference generated by the API.
`upiurl`	String	UPI link generated for customer mandate approval.

Error Handling

Status Code	Description	Action
`0`	API operation failed.	Check the response message and review the request parameters.
`2`	API operation is pending.	Use the relevant status API to check the operation outcome.

If a request times out or its outcome is unknown, check the existing operation before submitting another mandate creation request.

Important Notes

MAX allows debit amounts up to the authorised mandate limit, while EXACT specifies the exact debit amount.
Use the appropriate plan configuration for the intended collection flow.
The orderId is your merchant reference, while mandateRef is generated by the API.
The returned UPI link must be presented to the customer for approval. Do not construct the link manually.
A successful mandate creation response does not confirm customer approval. Use the Mandate Details API to verify that mandateStatus becomes Active.
Do not manually initiate a debit that is already configured as firstDebitAmount in the automatic plan.

What's Next

Once the mandate is created, present the returned UPI link to the customer for approval. Then use the Mandate Details API to verify the mandate status.