JavaScript is disabled. Some features may not work. You can also read the static version: View text version

Register Mandate (Intent)

This API can be used to register a merchant intent mandate. The response parameters should be passed as it is in the deeplink url. Refer below table for mapping of response parameters to the deeplink url parameters. Merchant to add mandate details like recurrence, expiry etc in the URL to initiate mandate request from payer app.

Scroll inside to view more

Response Param	Deeplink URL Param	Type
AmountRule	amrule	Mandatory
Amount	am	Mandatory
blockFund	block	Conditional
First Debit Amount	fam	Conditional, read note below
HeadOrdId	orgid	Optional
MandateValidityStart	validitystart	Mandatory
MandateValidityEnd	validityend	Mandatory
MandateReccurenceRuleType	recurtype	Conditional
MandateReccurenceValue	recurvalue	Conditional
MandateReccurence	recur	Mandatory
MandateName	mn	Mandatory
OrderId	tr	Mandatory
PayeeName	pn	Mandatory
PayeeVPA	pa	Mandatory
PayeeMcc	mc	Mandatory
TxnPurpose	purpose	Mandatory. purpose 01 for ONETIME mandate
TxnInitiationMode	mode	Mandatory
TxnQRqrMedium	qrMedium	Optional
TxnQRqVer	ver	Optional
PayeeAmountCurrency	cu	Mandatory
TxnType	txnType	Mandatory
TxnNote	tn	Optional
TxnId	tid	Mandatory
TxnQRExpireTs	QRexpire	Optional
Revocable	rev	Conditional

For MCC:7322(Loan Repayment/EMI Collection) where mandate revoking is not allowed, rev=N in deeplink url.

For ONETIME mandate, purpose = 01

In the case of a one-time 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.

fam param conditions:
1. This should not be zero if the purpose code is 14
2. Should be less than the am, i.e. amount.

For mode information, please check “Initiation Mode” sub-module in “Miscellaneous” module.

Sample Deeplink URL

upi://mandate?amrule=MAX&tn=Merchantmandate&validityend=09112026&mode=04&mn=Merchantmandate&cu=INR&pn=MerchantMandate&purpose=14&fam=1.00&tid=YJP20231009dzY4Kb7aBs9dj22&pa=merchant@yespay&am=10.00&validitystart=27102023&recur=ASPRESENTED&tr=KBREMI2023100950O4DUdHugy54&mc=7322&txnType=CREATE&orgid=000000&rev=N

Host URLs for IOS:
ppe://mandate?
tez://upi/mandate?
paytmmp://mandate?

Merchant can then construct the URI and invoke the APP using chrome intent feature. It can also be used for generating the Dynamic UPI QR & display on Merchant App/Website for users to scan & pay from any UPI App.

The URI must be generated dynamically based on the parameters received in the response. Ensure that there are no spaces in the URI; any spaces should be encoded as %20

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.

PSP will reject the request if the customer approved the mandate with a different account details and send a failure callback to the merchant.

SBMD use case:

This feature allows merchants to block the funds in the customer account (like IPO) and debit as and when customer avails the services. Following constraints have to be taken care of to create a successful SBMD Mandate.

Purpose should be 77.
Recurrence Pattern (MandateReccurence) should be ASPRESENTED.
blockFund should be True.
payerRevocable should be False.

Request

Response

API Endpoints

Production Link

POST

{{host}}/api/{{uri}}/merchants/transactions/registerIntent

                      jpupi-routing-id
                      *
                      

String

Mandatory

Header value should be same as of merchantRequestId sent in request body

Body

Request Schema: application/json

                      merchantRequestId
                      *
                      

String

Mandatory

Merchant generated unique id for the Mandate Creation.

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

                      amount
                      
                      

String

Optional But Mandatory For New Integration

Amount of intent transaction being registered.

Amount in two decimals. Decimals are mandatory.

                      intentRequestExpiryMinutes
                      
                      

String

Optional But Mandatory For New Integration

Minutes for which intent is valid. It should be <= order fulfilment time.

Constraint: number > 0

                      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.

                      flow
                      *
                      

String

Mandatory

In order to differentiate between transactions and mandates.

Values: TRANSACTION or MANDATE

                      refUrl
                      
                      

String

optional

Reference url for the intent transaction being registered.

                      refCategory
                      
                      

String

optional

Details for refUrl for the intent transaction being registered, whether it is 01 (Advertisement), 02(Invoice)

                      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 : ^[^/#-()*!%~`]+$

                      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.

Response Body

                      status
                      *
                      

String

Mandatory

PSP 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
                      *
                      

String

Mandatory

                      merchantId
                      *
                      

String

Mandatory

Unique id for the merchant as passed in request headers

                      merchantChannelId
                      *
                      

String

Mandatory

Unique id for the merchant channel as passed in request headers

                      gatewayTransactionId
                      *
                      

String

Mandatory

Gateway transaction id to be used for the intent transaction

Values:String as passed in the request

                      orderId
                      *
                      

String

Mandatory

Transaction refernce to be used for the intent transaction

                      payeeVpa
                      *
                      

String

Mandatory

Payee VPA to be used for the intent transaction

                      payeeName
                      *
                      

String

Mandatory

Payee name to be used for the intent transaction

                      payeeMcc
                      *
                      

String

Mandatory

Payee mcc to be used for the intent transaction

                      amount
                      *
                      

String

Mandatory

Amount to be used for the intent transaction

Values:String as passed in the request

                      currency
                      *
                      

String

Mandatory

Currency to be used for the intent transaction

                      remarks
                      
                      

String

optional

Remarks to be used for the intent transaction

Values:String as passed in the request

                      flow
                      *
                      

String

Mandatory

In order to differentiate between transactions and mandates. It can take the values as TRANSACTION or MANDATE.

Values:TRANSACTION or MANDATE

                      refUrl
                      *
                      

String

Mandatory

Reference URL to be used for the intent transaction

Values:String as passed in the request

                      refCategory
                      *
                      

String

Mandatory

Reference URL category to be used for the intent transaction

Values:String as passed in the request

                      payerAccountHashes
                      
                      

Array of String

optional

Hashed value of accounts to be passed by merchant for TPV.

                      udfParameters
                      
                      

Stringified JSON

optional

Merchant Defined Parameters

Example: "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}"