Setu
UPI Setu

Create

API Playground

Create recurring mandate

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

Intent based

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

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
Header

merchantId
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.

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 (if no validation errors are encountered on UPI Setu during mandate creation)

  • 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 due to mandate intent / qr expiry)

  • 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.

Collect based

The process for mandate creation is described in the below diagram: 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
Header

merchantId
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": "00",
    "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 a collect based recurring mandate
parametervalue
creationModecollect
initiationMode00 if creationMode is collect
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.

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": "initiated",
  "transactionNote": "Transaction note",
  "txnId": "BTTZrc5gDFkuCr3n3I0ey4aNtzLOLR7K7aR"
}
In the above response:

  • id is a unique mandate ID that is associated with this mandate and can be used to track it later.

This request to trigger mandate creation via collect flow is flexible and allows for many use cases. To know more about all the API params, please refer to the API documentation here. Post this, once the customer clicks on the mandate creation notification and enters the mPIN, the merchant will receive a webhook for following events:

  • 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}
Header

merchantId
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.

NextPre debit notification

On this page

Create recurring mandateIntent basedas presenteddailyperiodicCollect basedas presenteddailyperiodicCheck mandate status