Body
Create Mandate
This api will be used for creation of a mandate. It can be initiated by both Payer as well as Payee for mandate creation.
There are following scenarios :
1) When Payee creates a mandate, it requires mandate approval from Payer side. Cred block is not required for this case.
2) When Payer creates a mandate, then cred block is required and no approval is required.
Request
Response
API Endpoints
Production Link
POST
http://{{host}}/api/{uri}/merchants/mandates/create
Headers
Content-Type
*
string
Required
application/json
x-merchant-id
*
string
Required
Will be shared while onboarding.
x-merchant-channel-id
*
string
Required
Will be shared while onboarding.
Accept
*
string
Required
application/json
x-timestamp
*
string
Required
This is an epoch unix timestamp string. For example, 1496918882000. It can be used by us to invalidate older requests.
Parameter
amount
*
String
Mandatory
Amount for 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:MAX,EXACT
bankAccountUniqueId
*
String
Mandatory
Unique id for the selected bank account
Constraints:bankAccountUniqueId in the response of Fetch Accounts api call.
blockFund
optional
Boolean String
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. If blockFund and payerRevocable are both send false for a request then request will be rejected. Default value is false.
Constraints:String - true,false
credBlock
optional
Json String
Encrypted credblock containing user mpin. It is required if mandate is initiatedBy Payer.
Constraints:As returned by Common Library
currency
optional
String
Currency code
Constraints:String - INR
deviceFingerPrint
optional
String
Device fingerprint of the customer. It is required if mandate is initiatedBy Payer.
expiry
optional
String
Constraints:Minutes for which request is valid. Only applicable if initiatedBy PAYEE
Constraints:A numeric string between 2 to 64800 (both inclusive)
initiatedBy
*
String
Mandatory
Describes whether PAYER or PAYEE has initiated the create mandate request.
Constraints:PAYER,PAYEE
makeAsync
optional
Boolean
Denotes whether the API call will be done in synchronous or asynchronous manner. If it is not passed by default API call will be in synchronous. It is not required if initiatedBy PAYEE as it will be default async as it required approval from Customer.
Constraints:true,false
mandateName
*
String
Mandatory
Name of the mandate
merchantCustomerId
*
String
Mandatory
Merchant generated unique profile id for customer
Constraints:Alphanumeric string with dot(.). Maximum length is 256.
merchantRequestId
*
String
Mandatory
Merchant generated id for the mandate request
Constraints:35 character alphanumeric unique id.
payeeVpa
*
String
Mandatory
Vpa of the payee.
Constraints:Valid VPA
payerRevocable
optional
Boolean String
Defines whether mandate is revocable by PAYER or not. Applicable only when it is ONETIME mandate and initiatedBy PAYEE. For recurring mandate it should always be true, for onetime it can be true or false. If blockFund and payerRevocable are both send false for a request then request will be rejected. Default value is true.
Constraints:String - true/false.
payerVpa
*
String
Mandatory
Vpa of the payer.
Constraints:Valid VPA
recipientName
*
String
Mandatory
Name against which mandate is triggered. If initiatedBy is PAYER then payeeName or vice-versa. If name is not present with merchant payerVpa can be sent.
recurrencePattern
*
String
Mandatory
Recurrence Pattern for Mandate. Denotes at what frequency mandate can be executed.
Constraints:ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule
optional
String
Recurrence Rule for Mandate. It is not required for ONETIME, DAILY and ASPRENTED recurrencePattern.
Constraints:ON, BEFORE, AFTER.
recurrencValue
optional
String
Recurrence Value for Mandate. It is not required for ONETIME, DAILY and ASPRENTED recurrencePattern.
Constraints:between 1-31 and depends on recurrencePattern.
refUrl
optional
String
Reference url for the mandate. It is mainly kept for future purpose for invoice in inbox feature, 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
shareToPayee
String
optional
Descibes whether mandate will be shared with payee or not. Required only when it is ONETIME mandate and initiatedBy PAYER. For recurring mandate it should always be true, for onetime it can be true or false. Default value is true.
Constraints:String - true,false
transactionType
*
String
Mandatory
Type of Mandate Creation. UPI_MANDATE should be used for normal requests. QR_MANDATE should be used if mandate is created using QR. INTENT_MANDATE should be used if mandate is created using intent flow. P2M_MANDATE should be used if customer is directly creating a mandate with payeeVpa of merchant.
Constraints:UPI_MANDATE, QR_MANDATE, INTENT_MANDATE, P2M_MANDATE
udfParameters
JSON string
optional
Stringified JSON for udf parameters
upiRequestId
*
String
Mandatory
Unique id sent to UPI switch for the request
Constraints:35 character alphanumeric. Should always start with a unique merchant prefix. Max length is 35.
validityEnd
*
String
Mandatory
Date before which mandate can be execute
Constraints:String with proper date format YYYY/MM/DD
validityStart
*
String
Mandatory
Date after which mandate can be executed
Constraints:String with proper date format YYYY/MM/DD
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
transactionReference
String
optional
Transaction reference id
purpose
String
optional
Defines the purpose code of the mandate
Constraints:Numeric String
initiationMode
String
optional
Defines the initiationMode of the mandate
Constraints:Numeric String
umn
String
Optional
Unique mandate number. Only applicable for PAYER initiated mandate. If not passed, it is autogenerated.
mcc
String
Optional
Merchant category code
clVersion
String
Optional
Common Library Version of the UPI application clVersion
Constraints: Common Library Version of the UPI application (Mandatory for BioAuth payments)
200 : Success
Response Body
status
*
String
Mandatory
PSP status of the API
Values:SUCCESS, FAILURE
responseCode
*
String
Mandatory
PSP response code for the API
Values:Refer error code section
responseMessage
*
String
Mandatory
PSP response code for the API
Values:Refer error code section
payload
json
amount
*
String
Mandatory
Amount for mandate
Values:Numeric String with two decimals. As passed for amount 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.
bankAccountUniqueId
*
String
Mandatory
Unique id for the selected bank account
Values:bankAccountUniqueId in the response of Fetch Accounts api call. As passed for bankAccountUniqueId in request.
blockFund
String
optional
Defines whether customer's fund should be blocked or not. For onetime mandate it can be true or false. Default value is false.
Values:String - true, false
expiry
String
optional
Timestamp upto which mandate creation request is valid. It will only be present if mandate is initiated by PAYEE.
Values: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
gatewayReferenceId
*
String
Mandatory
Customer reference number (rrn) for the mandate operation.
gatewayResponseCode
*
String
Mandatory
Response code returned by gateway for the mandate operation.
Values:Refer table below.
gatewayResponseMessage
*
String
Mandatory
Response message returned by gateway for the mandate operation.
gatewayResponseStatus
*
String
Mandatory
Response status returned by gateway
Values:SUCCESS, FAILURE
initiatedBy
*
String
Mandatory
Describes whether PAYER or PAYEE has initiated the mandate.
Values:As passed for initiatedBy in request.
makeAsync
String
optional
Denotes whether the API call will be done in synchronous or asynchronous manner
Values:Only present if passed in reqBody and same value as in request.
mandateApprovalTimestamp
*
String
Mandatory
Time instant at which create mandate request was approved. Only present if mandate type is create and approved.
Values:YYYY-MM-DDTHH:MM:SS+05:30.
mandateName
*
String
Mandatory
Name of the mandate.
Values:As passed for mandateName in request.
mandateTimestamp
*
String
Mandatory
Timestamp of when this request was attempted
Values:YYYY-MM-DDTHH:MM:SS+05:30
merchantChannelId
*
String
Mandatory
Unique id for the merchant channel.
Values:As passed for x-merchant-channel-id in request headers
merchantCustomerId
*
String
Mandatory
Merchant generated unique profile id for customer
Values:Alphanumeric string with dot(.). Maximum length is 256. As passed for merchantCustomerId in request.
merchantId
*
String
Mandatory
Unique id for the merchant.
Values:As passed for x-merchant-id in request headers
merchantRequestId
*
String
Mandatory
Merchant generated id for the mandate request.
Values:As passed for merchantRequestId in request body.
orgMandateId
*
String
Mandatory
upiRequestId of the create request.
Values:As passed for upiRequestId in the request.
payeeMcc
*
String
Mandatory
Merchant Category Code of the payee merchant.
payeeName
String
optional
Name of the Payee involved in mandate.
payeeVpa
*
String
Mandatory
VPA of payee
Values:As passed for payeeVpa in request
payerName
String
optional
Name of the Payer involved in mandate.
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
payerVpa
*
String
Mandatory
VPA of payer
Values:As passed for payerVpa in request
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 recurrencValue in request.
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
optional
Any mandate summary. If pssed in request, it will be same in response else a default value is send.
role
*
String
Mandatory
Role of the customer for this mandate.
Values:PAYER, PAYEE
shareToPayee
*
String
Mandatory
Descibes whether mandate will be shared with payee or not. For onetime mandate it can be true or false. Default value is true.
Values:String - true, false.
transactionType
*
String
Mandatory
Type of Mandate Creation
Values:As passed for transactionType in request.
umn
String
optional
Unique Mandate Number used for execution of the mandate. Will be sent only if mandate is initiated by Payer.
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
udfParameters
json String
Optional
Udf parameters as passed in the request.
Values:As passed for udfParameters in request
Have questions?
- Need help? Contact support
- LLM? Read llms.txt