--- page_title: Register Mandate (Intent) product: UPI Merchant Stack page_source: https://juspay.io/in/docs/upi-merchant-stack/docs/mandates/register-mandate-intent openapi: https://juspay.io/in/docs/api/swagger?document=https%3A%2F%2Fjuspay.io%2Fin%2Fdocs%2Fupi-merchant-stack%2Fdocs%2Fmandates%2Fregister-mandate-intent llms_txt: https://juspay.io/in/docs/llms.txt product_llms_txt: https://juspay.io/in/docs/upi-merchant-stack/llms.txt --- ## API Version: default # 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. | 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 & purpose AZ for Interoperable 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 | ### > **Note** > 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 142. Should be less than the am, i.e. amount. > > For **Interoperable** mandate, purpose = AZFor 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?](tez://upi/mandate?amrule=MAX&tn=Merchantmandate&validityend=09112026&mode=04&mn=Merchantmandate&cu=INR&pn=MerchantMandate&purpose=14&tid=YJP20231009dzY4Kb7aBs9dj22&pa=nammayatri@yespay&am=10.00&validitystart=26072024&recur=ASPRESENTED&tr=KBREMI2123100950O4DUdHugy54&mc=7322&txnType=CREATE&orgid=000000&rev=N)[paytmmp://mandate?](paytmmp://upi/mandate?amrule=MAX&tn=Merchantmandate&validityend=09112026&mode=04&mn=Merchantmandate&cu=INR&pn=MerchantMandate&purpose=14&tid=YJP20231009dzY4Kb7aBs9dj22&pa=nammayatri@yespay&am=10.00&validitystart=26072024&recur=ASPRESENTED&tr=KBREMI2123100950O4DUdHugy54&mc=7322&txnType=CREATE&orgid=000000&rev=N) 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. > **Note** > 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** .## Endpoints: - Production: {{host}}/api/{{uri}}/merchants/transactions/registerIntent ## Request Type: POST ## Content-Type: application/json ## 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 curl -L -X POST '{{host}}/api/{{uri}}/merchants/transactions/registerIntent' \ -H 'content-type: application/json' \ -H 'x-merchant-id: TEST' \ -H 'x-merchant-channel-id: TESTAPP' \ -H 'x-timestamp: 1700158230380' \ -H 'jpupi-routing-id: ORDMxNameTransaction170357165578' \ --data-raw '{ "signature":"kHeeZD0f3E...", "payload":"eyJtZXJjaG...", "protected":"eyJhbGciOi..." }' ``` ### Sample Request and Response: #### Request: ```json { "merchantRequestId": "ORDMxNameTransaction170357165578", "amount": "2.00", "intentRequestExpiryMinutes": "10", "remarks": "Payment for order", "flow": "MANDATE", "refUrl": "www.xyz.com", "refCategory": "01", "iat": "1700158230380", "udfParameters": "{}", "payerAccountHashes": [ "ef907b670f92ba102daeadb0a9ea347c44bde9f4340e9330dd2ff3a674", "ef907b670f92ba102daeadb0a9ea347c44bde9f4340e9330ddaka" ] } ``` #### Response: ```json { "status": "SUCCESS", "responseCode": "SUCCESS", "responseMessage": "SUCCESS", "payload": { "merchantId": "TEST", "merchantChannelId": "TESTAPP", "merchantRequestId": "ord50894574", "gatewayTransactionId": "TXNef1a2908395239df56663244f8c7deaa", "orderId": "ord50894574", "payeeVpa": "merchant@xyz", "payeeName": "John Doe", "payeeMcc": "1520", "amount": "2.00", "currency": "INR", "payerAccountHashes": [ "ef907b670f92ba102daeadb0a9ea347c44bde9f4340e9330dd2ff3a674", "ef907b670f92ba102daeadb0a9ea347c44bde9f4340e9330ddaka" ], "remarks": "Payment for order", "refUrl": "www.xyz.com", "refCategory": "01" }, "udfParameters": "{}" } ``` ## Body Parameters: ### Basic Params: #### merchantRequestId: - Description: Merchant generated unique id for the Mandate Creation. **Constraint:** Max**** 35 characters alphanumeric, can also contain hyphen(-), dot(.) & underscore(_). - Value: value - Tags: String, Mandatory #### amount: - Description: Amount of intent transaction being registered. Amount in two decimals. Decimals are mandatory. - Tags: String, Optional But Mandatory For New Integration #### intentRequestExpiryMinutes: - Description: Minutes for which intent is valid. It should be <= order fulfilment time. **Constraint:** number > 0 - Tags: String, Optional But Mandatory For New Integration #### 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 #### flow: - Description: In order to differentiate between transactions and mandates. Values: TRANSACTION or MANDATE - Tags: String, Mandatory #### refUrl: - Description: Reference url for the intent transaction being registered. - Tags: String, optional #### refCategory: - Description: Details for refUrl for the intent transaction being registered, whether it is 01 (Advertisement), 02(Invoice) - Tags: String, optional #### 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 ### 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: PSP 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. - Value: - **Payload**: - Tags: String, Mandatory - **MerchantId**: - Description: Unique id for the merchant as passed in request headers - Tags: String, Mandatory - **MerchantChannelId**: - Description: Unique id for the merchant channel as passed in request headers - Tags: String, Mandatory - **GatewayTransactionId**: - Description: Gateway transaction id to be used for the intent transaction **Values:** String as passed in the request - Tags: String, Mandatory - **OrderId**: - Description: Transaction refernce to be used for the intent transaction - Tags: String, Mandatory - **PayeeVpa**: - Description: Payee VPA to be used for the intent transaction - Tags: String, Mandatory - **PayeeName**: - Description: Payee name to be used for the intent transaction - Tags: String, Mandatory - **PayeeMcc**: - Description: Payee mcc to be used for the intent transaction - Tags: String, Mandatory - **Amount**: - Description: Amount to be used for the intent transaction **Values:** String as passed in the request - Tags: String, Mandatory - **Currency**: - Description: Currency to be used for the intent transaction - Tags: String, Mandatory - **Remarks**: - Description: Remarks to be used for the intent transaction **Values:** String as passed in the request - Tags: String, optional - **Flow**: - Description: In order to differentiate between transactions and mandates. It can take the values as TRANSACTION or MANDATE. **Values:** TRANSACTION or MANDATE - Tags: String, Mandatory - **RefUrl**: - Description: Reference URL to be used for the intent transaction **Values:** String as passed in the request - Tags: String, Mandatory - **RefCategory**: - Description: Reference URL category to be used for the intent transaction **Values:** String as passed in the request - Tags: String, Mandatory - **PayerAccountHashes**: - Description: Hashed value of accounts to be passed by merchant for TPV. - Tags: Array of String, optional - Tags: String, Mandatory #### udfParameters: - Description: Merchant Defined Parameters Example: "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}" - Tags: Stringified JSON, optional --- ## See Also - [Mandate Execution](https://juspay.io/in/docs/upi-merchant-stack/docs/mandates/mandate-execution) - [Web Mandate (Collect)](https://juspay.io/in/docs/upi-merchant-stack/docs/mandates/web-mandate-collect)