Setu
UPI Setu

Create

API Playground

Create reserve mandate

There are two ways to create a Reserve mandate—Intent based and 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": "one time",
    "initiationMode": "01",
    "maxAmountLimit": 1000,
    "merchantReferenceId": "ABC1234789",
    "merchantVpa": "acme.corp@axis",
    "productConfigId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "purpose": "14",
    "recurrenceRule": "on",
    "recurrenceValue": 0,
    "shareToPayee": false,
    "startDate": "02012006",
    "transactionNote": "Transaction note"
}
Request body parameter values for creating an intent based one time mandate
parametervalue
frequencyone time
creationModeintent or qr
initiationMode

01 if creationMode is qr

04 if creationMode is intent

recurrenceValue0
recurrenceRuleon
autoExecutefalse
autoPreNotifyfalse
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": "one time",
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "initiationMode": "01",
    "intentLink": "upi://mandate?pa=acme.corp@axis&pn=merchant-1&validitystart=02012006&validityend=02012008&am=100.00&amrule=MAX&recur=ONETIME&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": 0,
    "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. Post this, once the customer clicks on the intent link / scans the qr code and enters the mPIN, the merchant will receive webhooks for following events:

  • 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

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": "collect",
    "currency": "INR",
    "customerRevocable": false,
    "customerVpa": "ram@axis",
    "endDate": "02012008",
    "expireAfter": 120,
    "firstExecutionAmount": 0,
    "frequency": "one time",
    "initiationMode": "00",
    "maxAmountLimit": 1000,
    "merchantReferenceId": "ABC1234789",
    "merchantVpa": "acme.corp@axis",
    "productConfigId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "purpose": "14",
    "recurrenceRule": "on",
    "recurrenceValue": 0,
    "shareToPayee": false,
    "startDate": "02012006",
    "transactionNote": "Transaction note"
}
Request body parameter values for creating a collect based one time mandate
parametervalue
frequencyone time
creationModecollect
initiationMode00 if creationMode is collect
recurrenceValue0
recurrenceRuleon
autoExecutefalse
autoPreNotifyfalse
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": "one time",
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "initiationMode": "00",
    "maxAmountLimit": 1000,
    "merchantId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "merchantReferenceId": "ABC1234789",
    "merchantVpa": "acme.corp@axis",
    "productConfigId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "purpose": "14",
    "recurrenceRule": "on",
    "recurrenceValue": 0,
    "shareToPayee": false,
    "startDate": "02012006",
    "status": "pending",
    "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.

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": "one time",
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "initiationMode": "00",
    "maxAmountLimit": 1000,
    "merchantId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "merchantReferenceId": "ABC1234789",
    "merchantVpa": "acme.corp@axis",
    "productConfigId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "purpose": "14",
    "recurrenceRule": "on",
    "recurrenceValue": 0,
    "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 execution APIs.

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

Reserve

UPI Setu - Mandates - Reserve

Execute

UPI Setu - Mandates - Execute Reserve Mandate

On this page

Create reserve mandate