---
page_source: https://juspay.io/in/docs/upi-merchant-stack/docs/mandates/web-mandate-collect
page_title: Web Mandate (Collect)
---

## API Version: default


# Web Mandate (Collect)



This api will be used for requesting the mandate by Merchant to the Payer.


### **TPV Use case:** 



For TPV (Third Party Validation) payerAccountHashes needs to be passed in the request body and the same will be passed back in response along with corresponding values. PayerAccountHashes will be taken as an array so that merchants can send multiple account hashes which will be verified against the account details selected by user shared by NPCI.

In web mandate, as merchant PSP does not have any control on the mandate, PSP will only be able to verify it once the mandate setup is completed and final confirmation comes to PSP.Hence, PSP will be sending tpvValidationStatus in the callback response to identify if the TPV validation is successful or not, according to which merchant has to revoke the corresponding mandate.## Endpoints:
- Production: {{host}}/api/{{uri}}/merchants/mandates/webMandate

## Request Type: 
POST

## Headers:

#### jpupi-routing-id:
Header value should be same as of **merchantRequestId**  sent in request body
- Tags: String, Mandatory
## Sample Code Snippets:
### Code Snippets:

#### Shell Code Snippet:

```shell
{"success":false,"message":"No Data found for the given path"}
```

### Sample Request and Response:

#### Request:
```json
{"success":false,"message":"No Data found for the given path"}
```

#### Response:
```json
{"success":false,"message":"No Data found for the given path"}
```

## Body Parameters:
### Basic Params:

#### amount:
- Description: Amount for which merchant requested the mandate

**Constraints:** Amount in two decimals. Decimals are mandatory.
- Tags: String, Mandatory

#### amountRule:
- Description: Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.

**Constraints:** String but only allowed values are EXACT / MAX
- Tags: String, Mandatory

#### blockFund:
- Description: Denotes whether customer's fund should be blocked or not. Only applicable for ONETIME mandate. For recurring mandate it should always be false, for onetime it can be true or false. Default value is false.

**Constraints:** String - true, false

For SBMD Flow the blockFund needs to be true.whenever blockFund is true  (for e.g. onetime mandate), a **revoke action by the merchant should be performed before the validity end date**  to release the funds if the execution has not been carried out. Otherwise, the amount will remain blocked at the customer’s bank.
- Tags: String, optional

#### customerVpa:
- Description: VPA on which request mandate should be triggered

**Constraint:**  VPA should only contain a-z, 0-9, . (dot), - (hyphen).
- Tags: String, Mandatory

#### mandateName:
- Description: Name of the mandate
- Tags: String, Mandatory

#### mandateRequestExpiryMinutes:
- Description: Minutes for which request is valid

**Constraints:** A number between 2 to 64800, both inclusive, in String format.
- Tags: String, Mandatory

#### merchantRequestId:
- Description: Merchant generated unique id for Mandate Creation.

**Constraint:** Max 35 characters alphanumeric, can also contain hyphen(-), dot(.) & underscore(_)
- Tags: String, Mandatory

#### payerRevocable:
- Description: Defines whether mandate is revocable by PAYER or not. 

* For ONETIME mandate initiated by PAYEE it has to be false when blockFund is true.
* For SBMD Flow payerRevocable needs to be always **false** .
* For recurring mandate it should always be true except for the MCC:7322(Loan Repayment/EMI Collection) where mandate revoking is not allowed.
* Default value is true.

**Value:**  true/false
- Tags: String, optional

#### recurrencePattern:
- Description: Recurrence Pattern for Mandate. Denotes at what frequency mandate can be executed.

**Value:** ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED

For **SBMD**  flow, the recurrencePattern should be ASPRESENTED
- Tags: String, Mandatory

#### recurrenceRule:
- Description: Recurrence Rule for Mandate. It is not required for ONETIME, DAILY and ASPRESENTED recurrencePattern.

**Constraints:** ON, BEFORE, AFTER.
- Tags: String, conditional

#### recurrenceValue:
- Description: Recurrence Value for Mandate. It is not required for ONETIME, DAILY and ASPRESENTED recurrencePattern.

**Constraints :** Depends on recurrencePattern. The value should be between 1-31 for month, 1(Monday)-7(Friday) for week.
- Tags: String, Conditional

#### refCategory:
- Description: Details for refUrl, whether it is 01 (advertisement), 02(Invoice). If nothing is passed, a default value of "00" is set up and same will be sent back in response.

**Constraints:** Numeric String
- Tags: String, optional

#### refUrl:
- Description: Invoice as sent by merchant or reference to the mandate in the form of url. If nothing is passed then a default value is set for this tag and same will be send back in response.
- Tags: String, optional

#### remarks:
- Description: Any mandate summary for creation.**Constraint:** The transaction note must be alphanumeric, with a **minimum length of 1 character and a maximum length of 50**  characters.
- Tags: String, optional

#### validityEnd:
- Description: Date before which mandate can be execute

**Format:** String with proper date format YYYY/MM/DD
- Tags: String, Mandatory

#### validityStart:
- Description: Date after which mandate can be executed

**Format:** String with proper date format YYYY/MM/DD
- Tags: String, Mandatory

#### iat:
- Description: Current Epoch Unix timestamp string. Has to be of 13 digit in Milliseconds.

Example: 1496918882000.
- Tags: String, Mandatory

#### udfParameters:
- Description: Merchant Defined Parameters

**Example** : "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}"**Note** : Few special characters are not allowed. Regex for the characters which are not allowed : **^[^/#-()*!%~`]+$** 
- Tags: Stringified JSON, Optional

#### Purpose:
- Description: * For ONETIME mandate Purpose code needs to be “01”.
* For SBMD flow Purpose code needs to be “77”.
- Tags: String, Conditional
### TPV Params:

#### payerAccountHashes:
- Description: Hashed value of accounts to be passed by merchant for TPV.**Hashing logic:** 

payerAccountHash = sha256( account Number + first 4 digit of account IFSC)From account Number the leading zeros should be removed and then the hash should be calculated.Eg: Account No. = 0000123456789 & IFSC = ABCD0000345

Hash will be calculated on 123456789ABCD.
- Value: value
- Tags: Array of String, Optional
## API Responses:
### 200:

#### status:
- Description: Status of the API.

**Values:** SUCCESS, FAILURE
- Tags: String, Mandatory

#### responseCode:
- Description: PSP response code for the API.

**Values:** Refer Codes Guide in Resource Section.
- Tags: String, Mandatory

#### responseMessage:
- Description: PSP response message for the API.

**Values:** Refer Codes Guide in Resource Section.
- Tags: String, Mandatory

#### payload:
- Value:
  - **Amount**:
    - Description: Amount for which merchant requested the mandate
      
      **Values:** As passed in request.
    - Tags: String, Mandatory
  - **AmountRule**:
    - Description: Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
      
      **Values:** As passed for amountRule in request.
    - Tags: String, Mandatory
  - **CustomerVpa**:
    - Description: VPA on which request mandate should be triggered
      
      **Values:** As passed in request
    - Tags: String, Mandatory
  - **Expiry**:
    - Description: Minutes for which request is valid
      
      **Format:** Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format, request timestamp plus expiry minutes passed in request.
    - Tags: String, Mandatory
  - **GatewayMandateId**:
    - Description: UPI request id returned by gateway for the mandate
      
      **Values:** As passed for upiRequestId in request
    - Tags: String, Mandatory
  - **GatewayResponseCode**:
    - Description: Response code returned by gateway for the transaction.
      
      **Values:** 00
    - Tags: String, Mandatory
  - **GatewayResponseMessage**:
    - Description: Response message returned by gateway for the transaction.
    - Tags: String, Mandatory
  - **GatewayResponseStatus**:
    - Description: Response status returned by gateway.
      
      **Values:** SUCCESS, FAILURE
    - Tags: String, Mandatory
  - **MandateName**:
    - Description: Name of the mandate
      
      **Values:** As passed in request
    - Tags: String, Mandatory
  - **MandateTimestamp**:
    - Description: Timestamp of when the webMandate was initiated
      
      **Format:** (YYYY-MM-DDTHH:MM:SS+05:30)
    - Tags: String, Mandatory
  - **MerchantChannelId**:
    - Description: Unique id for the channel via which request is made.
      
      **Values:** As passed in request.
    - Tags: String, Mandatory
  - **MerchantId**:
    - Description: Unique id for merchant.
      
      **Values:** As passed in request.
    - Tags: String, Mandatory
  - **MerchantRequestId**:
    - Description: Merchant generated unique id for collect request.
      
      **Constraint** : Max 35 characters & Alphanumeric.
    - Tags: String, Mandatory
  - **OrgMandateId**:
    - Description: Refers to upiRequestId used during creation of mandate
      
      **Values:** As passed for upiRequestId in the request.
    - Tags: String, Mandatory
  - **PayerRevocable**:
    - Description: Defines whether mandate is revocable by PAYER or not. For onetime mandate it can be true or false. Default value is true.
      
      **Values:** String - true, false
    - Tags: String, Mandatory
  - **RecurrencePattern**:
    - Description: Recurrence Pattern for Mandate
      
      **Values:** As passed for recurrencePattern in request
    - Tags: String, Mandatory
  - **RecurrenceRule**:
    - Description: Recurrence Rule for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.
      
      **Values:** As passed for recurrenceRule in request
    - Tags: String, conditional
  - **RecurrencValue**:
    - Description: Recurrence Value for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.
      
      **Values:** As passed for recurrenceRule in request
    - Tags: String, conditional
  - **RefCategory**:
    - Description: Details for refUrl, whether it is 01 (advertisement), 02(Invoice). It will be same value if passed in request, else a default value of "00" is sent.
      
      **Values:** Numeric String
    - Tags: String, Mandatory
  - **RefUrl**:
    - Description: Reference url for the mandate. It will be same value if passed in request else it will be a default url.
    - Tags: String, Mandatory
  - **Remarks**:
    - Description: Any mandate summary. If pssed in request, it will be same in response else a default value is send.
    - Tags: String, Mandatory
  - **ValidityEnd**:
    - Description: Date before which mandate can be executed.
      
      **Values:** As passed for validityEnd in request
    - Tags: String, Mandatory
  - **ValidityStart**:
    - Description: Date after which mandate can be executed.
      
      **Values:** As passed for validityStart in request
    - Tags: String, Mandatory
  - **BlockFund**:
    - Description: Denotes whether customer's fund should be blocked or not. Only applicable for ONETIME mandate. For recurring mandate it should always be false, for onetime it can be true or false. Default value is false.
      
      **Constraints:** String - true,false
    - Tags: String, optional
  - **CustomerName**:
    - Description: Name of the payer
    - Tags: String, optional
  - **OriginalMerchantRequestId**:
    - Description: Merchant request of the original transaction
    - Tags: String, optional
  - **PayerAccountHashes**:
    - Description: As passed in the request body.
    - Tags: Array of String, optional
- Tags: json, Mandatory

#### udfParameters:
- Description: Merchant Defined Parameters

Example: "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}"
- Tags: Stringified JSON, optional