Body
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.
Request
Response
API Endpoints
Production Link
POST
{{host}}/api/{{uri}}/merchants/mandates/webMandate
Headers
jpupi-routing-id
*
String
Mandatory
Header value should be same as of merchantRequestId sent in request body
Basic Params
amount
*
String
Mandatory
Amount for which merchant requested the mandate
Constraints:Amount in two decimals. Decimals are mandatory.
amountRule
*
String
Mandatory
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
blockFund
String
optional
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.
customerVpa
*
String
Mandatory
VPA on which request mandate should be triggered
Constraint: VPA should only contain a-z, 0-9, . (dot), - (hyphen).
mandateName
*
String
Mandatory
Name of the mandate
mandateRequestExpiryMinutes
*
String
Mandatory
Minutes for which request is valid
Constraints:A number between 2 to 64800, both inclusive, in String format.
merchantRequestId
*
String
Mandatory
Merchant generated unique id for Mandate Creation.
Constraint: Max 35 characters alphanumeric, can also contain hyphen(-), dot(.) & underscore(_)
payerRevocable
String
optional
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
recurrencePattern
*
String
Mandatory
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
recurrenceRule
String
conditional
Recurrence Rule for Mandate. It is not required for ONETIME, DAILY and ASPRESENTED recurrencePattern.
Constraints:ON, BEFORE, AFTER.
recurrenceValue
String
Conditional
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.
refCategory
String
optional
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
refUrl
String
optional
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.
remarks
String
optional
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.
validityEnd
*
String
Mandatory
Date before which mandate can be execute
Format:String with proper date format YYYY/MM/DD
validityStart
*
String
Mandatory
Date after which mandate can be executed
Format:String with proper date format YYYY/MM/DD
iat
*
String
Mandatory
Current Epoch Unix timestamp string. Has to be of 13 digit in Milliseconds.
Example: 1496918882000.
udfParameters
Stringified JSON
Optional
Merchant Defined Parameters
Example: "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}"
Note: Few special characters are not allowed. Regex for the characters which are not allowed : ^[^/#-()*!%~`]+$
Purpose
String
Conditional
For ONETIME mandate Purpose code needs to be “01”.
For SBMD flow Purpose code needs to be “77”.
TPV Params
payerAccountHashes
Array of String
Optional
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.
200 : Success
Response Body
status
*
String
Mandatory
Status of the API.
Values:SUCCESS, FAILURE
responseCode
*
String
Mandatory
PSP response code for the API.
Values: Refer Codes Guide in Resource Section.
responseMessage
*
String
Mandatory
PSP response message for the API.
Values: Refer Codes Guide in Resource Section.
payload
*
json
Mandatory
amount
*
String
Mandatory
Amount for which merchant requested the mandate
Values:As passed in request.
amountRule
*
String
Mandatory
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.
customerVpa
*
String
Mandatory
VPA on which request mandate should be triggered
Values:As passed in request
expiry
*
String
Mandatory
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.
gatewayMandateId
*
String
Mandatory
UPI request id returned by gateway for the mandate
Values:As passed for upiRequestId in request
gatewayResponseCode
*
String
Mandatory
Response code returned by gateway for the transaction.
Values:00
gatewayResponseMessage
*
String
Mandatory
Response message returned by gateway for the transaction.
gatewayResponseStatus
*
String
Mandatory
Response status returned by gateway.
Values:SUCCESS, FAILURE
mandateName
*
String
Mandatory
Name of the mandate
Values:As passed in request
mandateTimestamp
*
String
Mandatory
Timestamp of when the webMandate was initiated
Format:(YYYY-MM-DDTHH:MM:SS+05:30)
merchantChannelId
*
String
Mandatory
Unique id for the channel via which request is made.
Values: As passed in request.
merchantId
*
String
Mandatory
Unique id for merchant.
Values:As passed in request.
merchantRequestId
*
String
Mandatory
Merchant generated unique id for collect request.
Constraint: Max 35 characters & Alphanumeric.
orgMandateId
*
String
Mandatory
Refers to upiRequestId used during creation of mandate
Values:As passed for upiRequestId in the request.
payerRevocable
*
String
Mandatory
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
recurrencePattern
*
String
Mandatory
Recurrence Pattern for Mandate
Values:As passed for recurrencePattern in request
recurrenceRule
String
conditional
Recurrence Rule for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.
Values:As passed for recurrenceRule in request
recurrencValue
String
conditional
Recurrence Value for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.
Values: As passed for recurrenceRule in request
refCategory
*
String
Mandatory
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
refUrl
*
String
Mandatory
Reference url for the mandate. It will be same value if passed in request else it will be a default url.
remarks
*
String
Mandatory
Any mandate summary. If pssed in request, it will be same in response else a default value is send.
validityEnd
*
String
Mandatory
Date before which mandate can be executed.
Values:As passed for validityEnd in request
validityStart
*
String
Mandatory
Date after which mandate can be executed.
Values:As passed for validityStart in request
blockFund
String
optional
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
customerName
String
optional
Name of the payer
originalMerchantRequestId
String
optional
Merchant request of the original transaction
payerAccountHashes
Array of String
optional
As passed in the request body.
udfParameters
Stringified JSON
optional
Merchant Defined Parameters
Example: "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}"
Have questions?
- Need help? Contact support
- LLM? Read llms.txt