—
–
/

to search

Introducing Setu Changelog Check it out ↗

Reading time — 8 minutes

Edit this page ↗

#Create recurring mandate

There are 2 ways to create a recurring mandate: Intent based, Collect based

The process for mandate creation is described in the below diagram:

Bridge

The merchant will have to call the create mandate API with the correct set of parameters.

Staging hosthttps://umap.setu.co/api
MethodPOST
Path/v1/merchants/mandates
HeadermerchantId
Authorization: Bearer <insert_token_here>. Generate this token using OAuth.

Content-Type—will be application/json
Sample request
{
    "allowMultipleDebit": false,
    "amount": 1000,
    "amountRule": "max",
    "autoExecute": false,
    "autoPreNotify": false,
    "blockFunds": false,
    "creationMode": "qr",
    "currency": "INR",
    "customerRevocable": false,
    "customerVpa": "ram@axis",
    "endDate": "02012008",
    "expireAfter": 120,
    "firstExecutionAmount": 0,
    "frequency": "weekly",
    "initiationMode": "01",
    "maxAmountLimit": 1000,
    "merchantReferenceId": "ABC1234789",
    "merchantVpa": "acme.corp@axis",
    "productConfigId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "purpose": "14",
    "recurrenceRule": "on",
    "recurrenceValue": 1,
    "shareToPayee": false,
    "startDate": "02012006",
    "transactionNote": "Transaction note"
}

Request body parameter values for creating an intent based recurring mandate

parametervalue
creationModeintent or qr
initiationMode

01 if creationMode is qr

04 if creationMode is intent

autoExecute

If the value of autoExecute and autoPreNotify is false then the merchant is responsible for triggering the pre debit notification and execution in every recurrence cycle.

autoPreNotify

If the value of autoExecute and autoPreNotify is true then no merchant intervention is needed and UPI Setu is responsible for triggering the pre debit notification and execution in every recurrence cycle.

Possible values and descriptions of frequency, recurrenceValue and recurrenceRule

frequencyrecurrenceValuerecurrenceRule
as presented0

on

pre debit notification, execution is triggered as and when the merchant makes pre debit notification / execution API calls to UPI Setu

Sample response
{
    "allowMultipleDebit": false,
    "amount": 1000,
    "amountRule": "max",
    "autoExecute": false,
    "autoPreNotify": false,
    "blockFunds": false,
    "createdAt": "2023-09-04T12:08:20+0530",
    "creationMode": "qr",
    "currency": "INR",
    "customerRevocable": true,
    "customerVpa": "ram@axis",
    "endDate": "02012008",
    "expireAfter": 120,
    "firstExecutionAmount": 0,
    "frequency": "weekly",
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "initiationMode": "01",
    "intentLink": "upi://mandate?pa=acme.corp@axis&pn=merchant-1&validitystart=02012006&validityend=02012008&am=100.00&amrule=MAX&recur=WEEKLY&recurvalue=1&recurtype=ON&tr=BTTZrc5gDFkuCr3n3I0ey4aNtzLOLR7K7aR&cu=INR&mc=1234&mode=01&purpose=14&rev=Y&share=N&qrexpire=02012006&block=N&orgid=409214&version=2.0&txnType=CREATE&tid=BTTZrc5gDFkuCr3n3I0ey4aNtzLOLR7K7aR",
    "maxAmountLimit": 1000,
    "merchantId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "merchantReferenceId": "ABC1234789",
    "merchantVpa": "acme.corp@axis",
    "productConfigId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "purpose": "14",
    "recurrenceRule": "on",
    "recurrenceValue": 1,
    "shareToPayee": false,
    "startDate": "02012006",
    "status": "pending",
    "transactionNote": "Transaction note",
    "txnId": "BTTZrc5gDFkuCr3n3I0ey4aNtzLOLR7K7aR"
}
In the above response:
  • `intentLink` or corresponding qr can be shared directly with customers via a communication channel.
  • `id` is a unique mandate ID that is associated with this mandate and can be used to track it later.

This request to generate a mandate creation intent link / qr is flexible and allows for many use cases. To know more about all the API params, please refer to the API documentation here.

  • mandate.initiated
  • mandate_operation.create.initiated
  • mandate.live (if mandate creation is successful)
  • mandate_operation.create.success (if mandate creation is successful)
  • mandate.rejected (if mandate creation fails)
  • mandate_operation.create.failed (if mandate creation fails)

Read more about mandate status notifications here and mandate create operation notifications here

In addition to the notifications, the merchant can also use check mandate status API to check if mandate is LIVE

Please refer to the Document Reference section for checking the API reference and the notifications.

#Check mandate status

In addition to the notifications sent by UPI Setu, Merchant can use this API to check the status of a mandate.

Staging hosthttps://umap.setu.co/api
MethodGET
Path/v1/merchants/mandates/{id}
HeadermerchantId
Authorization: Bearer <insert_token_here>. Generate this token using OAuth.

Content-Type—will be application/json
Sample response
{
    "allowMultipleDebit": false,
    "amount": 1000,
    "amountRule": "max",
    "autoExecute": false,
    "autoPreNotify": false,
    "blockFunds": false,
    "createdAt": "2023-09-04T12:08:20+0530",
    "creationMode": "collect",
    "currency": "INR",
    "customerRevocable": true,
    "customerVpa": "ram@axis",
    "endDate": "02012008",
    "expireAfter": 120,
    "firstExecutionAmount": 0,
    "frequency": "weekly",
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "initiationMode": "00",
    "maxAmountLimit": 1000,
    "merchantId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "merchantReferenceId": "ABC1234789",
    "merchantVpa": "acme.corp@axis",
    "productConfigId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "purpose": "14",
    "recurrenceRule": "on",
    "recurrenceValue": 1,
    "shareToPayee": false,
    "startDate": "02012006",
    "status": "live",
    "transactionNote": "Transaction note",
    "txnId": "BTTZrc5gDFkuCr3n3I0ey4aNtzLOLR7K7aR",
    "umn": "c27f5fc30d344e9594fce0afa34f8859@mypsp"
}
In the above response:
  • id is a unique mandate ID that is associated with this mandate and can be used to track it later.
  • umn is a unique mandate identifier that is associated with this mandate and is needed for pre debit notification and execution APIs.

To know more about all the API params, please refer to the API documentation here.

READ NEXT →

Pre debit notification

Send pre debit notification.