--- page_title: One Time Mandate product: API Reference page_source: https://juspay.io/in/docs/api-reference/docs/express-checkout/one-time-mandate llms_txt: https://juspay.io/in/docs/llms.txt product_llms_txt: https://juspay.io/in/docs/api-reference/llms.txt --- # One Time Mandate ## Overview The One-Time Mandate (OTM) allows merchants to block funds from a customer's account for a specific period. Merchants can then either: * **Capture** those funds later (debit the money). * **Release** the blocked funds back to the customer. This is required because there are scenarios where a delay is required(e.g., for processing or underwriting). “Juspay supports OTMs through the UPI payment method.” ## **How to Use the API for OTM** Merchants already integrated with mandates must update their integration to support OTM, based on their integration method: * **Direct API Merchants:** Add the required parameters in the **Order/Session API** request. * **PP/SDK Merchants:** Include these parameters in the **SDK process payload** . * **SDK Integration Resources** * **Payment Page SDK (Hyper Checkout):** [Integration Guide](https://juspay.io/in/docs/hyper-checkout/android/base-sdk-integration/open-hypercheckout-screen) * **Headless SDK (UPI Transaction Mandate):** [Payload Details](https://juspay.io/in/docs/ec-headless/android/payloads/upi?flows=UPI%2520Txn%2520-%2520Intent%2520Mandate) * **Signature-Based Integrations:** Ensure these parameters are part of the **order details payload** before signing. Regardless of the integration method, the following parameters must be sent in API requests to initiate the OTM flow: | Parameter | Type | Description | |---|---|---| | mandate.block_funds | Boolean | Set to true to initiate the fund blocking process. | | mandate.revokable_by_customer | Boolean | Set to false. The customer should not be able to revoke the mandate. | | mandate.frequency | String | Set to ONETIME to indicate this is a one-time mandate for premiums/ subscription or any other use case. | | mandate.start_date | Integer | The starting date of the mandate in Unix timestamp format (seconds). Use the current date. | | mandate.end_date | Integer | The ending date of the mandate. | ### Session Response Parameters | Parameter | Type | Description | |---|---|---| | status | String | Status of the order. Can be NEW, PENDING, CHARGED, FAILED, etc. | | id | String | Unique order ID generated by Juspay. | | order_id | String | Your order ID. | | payment_links.web | String | URL to the Juspay payment page. | | sdk_payload | Object | Payload required for SDK integration (if applicable). | | sdk_payload.requestId | String | Unique request ID for the SDK. | | sdk_payload.payload | Object | Contains parameters for the payment page, including mandate details. | | sdk_payload.payload.mandate.frequency | String | Indicates the frequency of the mandate, which is ONETIME. | | sdk_payload.payload.firstName | String | The first name of the customer. | | sdk_payload.payload.mandate.startDate | Integer | The start date of the mandate in Unix timestamp format (seconds). | | sdk_payload.payload.clientId | String | The ID of the client merchant. | | sdk_payload.payload.customerId | String | The ID of the customer. | | sdk_payload.payload.orderId | String | The ID of the order. | | sdk_payload.payload.returnUrl | String | The URL to redirect to after payment. | | sdk_payload.payload.currency | String | The currency of the payment. | | sdk_payload.payload.customerEmail | String | The email address of the customer. | | sdk_payload.payload.customerPhone | String | The phone number of the customer. | | sdk_payload.payload.service | String | Indicates the payment service used. | | sdk_payload.payload.metadata.webhookUrl | String | The URL to send webhook notifications to. | | sdk_payload.payload.description | String | A description of the payment. | | sdk_payload.payload.options.createMandate | String | Indicates whether the creation of a mandate is optional or required. | | sdk_payload.payload.mandate.blockFunds | Boolean | Indicates whether funds should be blocked. | | sdk_payload.payload.mandate.revokableByCustomer | Boolean | Indicates whether the customer can revoke the mandate. | | sdk_payload.payload.mandate.maxAmount | String | The maximum amount allowed for the mandate. | | sdk_payload.payload.environment | String | The environment in which the payment is processed. | | sdk_payload.payload.lastName | String | The last name of the customer. | | sdk_payload.payload.timestamp | String | The timestamp of the payment request. | | sdk_payload.payload.merchantId | String | The ID of the merchant. | | sdk_payload.payload.amount | String | The amount of the payment. | | sdk_payload.payload.clientAuthTokenExpiry | String | The expiration date and time of the client authentication token. | | sdk_payload.payload.clientAuthToken | String | The client authentication token. | | sdk_payload.payload.action | String | The action to be performed. | | sdk_payload.payload.mandate.endDate | Integer | The end date of the mandate. | ### Batch Mandates Merchants can process **One-Time Mandates (OTM)** in bulk using the **Batch Mandate** feature. This allows multiple mandates to be initiated in a single request, streamlining operations and reducing API calls. For detailed guidelines Refer to **[Batch Mandates Documentation](https://juspay.io/in/docs/api-reference/docs/express-checkout/merchant-exercises-the-mandate-from-the-dashboard)** > **Note** > This feature, like all mandates, is only available for **registered customers** and does **not support guest checkouts** . ## Webhooks and Order Status When an OTM is created, the following additional fields must be included in the **mandate block** within webhook notifications and order status updates: | Parameter | Value | |---|---| | block_fund | TRUE | | revokable_by_customer | FALSE | | frequency | ONETIME | > **Note** > Merchants must **validate** the **presence and values** of these fields in order status updates for accurate OTM processing. #### Mandate Block/ Order Amount Response #### Mandate Block Response Code Snippet: ```mandate block response "mandate": { "max_amount": 10000, "mandate_id": "FILTERED", "start_date": "1740218017", "end_date": "1741427617", "frequency": "ONETIME", "mandate_type": "EMANDATE", "mandate_token": "FILTERED", "revokable_by_customer": false, "amount_rule": "VARIABLE", "block_fund": true, "mandate_status": "ACTIVE" } ``` #### Order Amount Response Code Snippet: ```order amount response "order": { "maximum_eligible_refund_amount": 10000, "amount": 10000, "amount_debited": 10000, "effective_amount": 10000, } ``` Also, note these amount-related fields: * `maximum_eligible_refund_amount`, `amount`, and `effective_amount` will be equal to `mandate.max_amount`. * `amount_debited`will be the amount actually captured (which might be less than `mandate.max_amount` if you only capture part of the blocked amount). ## Post-Registration Flows ### **Mandate Execution** Use the **Mandate Execution API** to debit the blocked funds after successful mandate registration. This ensures that the payment is processed as per the predefined mandate conditions. * This action can be performed via API or directly from the Juspay dashboard. * [Refer to API Specs](https://juspay.io/in/docs/upi-autopay/docs/how-to-integrate/mandate-execution-api) #### Mandate Execution Request Code Snippet: ```mandate execution request curl --location 'https://api.juspay.in/txns' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'order.order_id=recu_1740825593' \ --data-urlencode 'mandate_id=vzHLoWeRPmL22fmae7FZ4' \ --data-urlencode 'order.amount=1' \ --data-urlencode 'merchant_id=merc_id' \ --data-urlencode 'format=json' \ --data-urlencode 'redirect_after_payment=true' --data-urlencode 'order.customer_id=0349' --data-urlencode 'order.order_type=MANDATE_PAYMENT' ``` #### Mandate Execution Response Code Snippet: ```mandate execution response "res_body": { "txn_id": "merchant_id-b43fee81-1", "order_id": "b43fee81", "status": "PENDING_VBV", "payment": { "authentication": { "url": "https://api.juspay.in/v2/pay/finish/getsimpl/mozw49bJPKyByAM/b43fee81", "method": "GET" } }, "offer_details": { "offers": [] }, "txn_uuid": "mozw49bJPKyByAM" }, ``` > **Note** > Notifications are **not required** for one-time mandates (OTM) on UPI. Therefore, notification-related parameters **should not** be included in the Mandate Execution API request. ### **Mandate Revoke** The **Mandate Revoke API** allows merchants to revoke an existing mandate before it is executed. This may be necessary if the user **withdraws** consent or if the service is no longer required. * Merchants can revoke a mandate through the API or via the Juspay dashboard. * Once revoked, the blocked funds will be released back to the user’s account.[Refer to API Specs](https://juspay.io/in/docs/upi-consumer-stack/docs/customer-mandates/updaterevoke-mandate) ### Mandate Update Mandates can be updated under certain conditions. * Changes can be made to update the mandate; however, explicit customer consent is required before modifying the **mandate amount.** * Updates are subject to the availability of this feature at the Payment Gateway (PG) level.[Refer to API Specs](https://juspay.io/in/docs/upi-consumer-stack/docs/customer-mandates/updaterevoke-mandate) ### **Auto-Release** If the mandate isn’t executed before `mandate.end_date`, funds auto-release to the user. * A **mandate revoke webhook** will trigger upon expiry. * The timeframe for auto-revocation may vary based on industry regulations and use case requirements. * **For example** , in the insurance sector, mandates are typically auto-revoked after 14 days if not utilized. ## Dashboard Configuration ### Step 1 Configuring a Gateway Configure a gateway that **supports** UPI One-Time Mandates. ### Step 2 Payment Method Configuration In the PG Control Centre, go to the Payment Method Configurations tab. **Enable UPI Collect** and **UPI Intent** from the Mandates/Subscriptions section. ### Step 3 eMandate setting Under Advanced Features, set "**Enable eMandate** " to _True_ . Save the changes. ### Step 4 Repeat Do this for all gateways/aggregators supporting OTM for your account. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/api-reference/Image-wwUPZ.png) *OTM Configuration* ## Supported Gateways: | Gateway | Current Stage | |---|---| | AXIS_BIZ | Live | | YES_BIZ | Live | | RBL_BIZ | Live | | PayU | Live | | BILLDESK | Integration Phase | | ICICI_UPI | Integration Phase | | Cashfree | Integration Phase | | CAMSpay | Integration Phase | ## Supported PSP Handles At present we support the below listed PSP’s | PSP Handle | PSP Handle | PSP Handle | PSP Handle | |---|---|---|---| | @ybl | @paytm | @upi | @ibl | | @axl | @boi | @cnrb | @okhdfcbank | | @okaxis | @axisbank | @postbank | @ikwik | | @barodampay | @apl | @indus | @dbs | | @icici | @okicici | @dlb | @sliceaxis | | @pz | @jio | @sbi | @axb | | @yesg | @yapl | @pnb | @oksbi | | @jupiteraxis | @shriramhdfcbank | @abfspay | @niyoicici | | @waicici | @centralbank | @equitas | @naviaxis | | @ypay | @axispay | @razorpay | @tapicici | | @Goaxb | @mahb | @fincarebank | @iob | | @indie | @pingpay | @yespay | @gocash | | @kotak | @kotak811 | @paytmwallet | @axisb | | @freecharge | @hdfcbank | @abcdicici | @sbipa | | @fifederal | @Payu | @timecosmos | @sib | | @ptyes | @ptaxis | @ptsbi | @pthdfc | | @oneyes | @seyes | @superyes | @ttyes | | @yescurie | @yesfam | @yestp | @gwaxis | | @rmrbl | @easebuzz | | | ## FAQ’s ## FAQs: ### Is partial capture of the blocked amount possible?  Yes, partial capture is possible. ### What happens to the remaining blocked amount? The remaining amount will be transferred back to the user's account immediately. > **Note** > For assistance, contact Juspay @ support@juspay.in ## Sample Code Snippets: ### Sample Request: #### Session Request Code Snippet: ```session request curl --location 'https://api.juspay.in/session' \ --header 'x-merchantid: testMerchant' \ --header 'Authorization: Basic OTNBRDU4NDVDNzQ0NjA3QTc2DkwNzM2OEM4Og=='\ --header 'Content-Type: application/json' \ --data-raw '{ "order_id": "1740207690", "timestamp": "1678343548", "first_name": "John", "last_name": "Wick", "customer_id": "Customer12345", "customer_email": "TEST@gmail.com", "customer_phone": "9999999999", "action":"paymentPage", "merchant_id": "testMerchant", "amount": "9000.00", "currency": "INR", "options.create_mandate":"REQUIRED", "mandate.block_funds": true, "mandate.revokable_by_customer": false, "mandate.frequency": "ONETIME", "mandate.max_amount":"10000.00", "mandate.start_date":"1775563443", "mandate.end_date":"1782557403", "description":"Payment Page", "payment_page_client_id": "testMerchant", "return_url": "https://www.google.com", "metadata.webhook_url":"https://payment.testMerchant.com/pages/ProcessJusPayResponse.aspx" }' ``` #### Create Order Request Code Snippet: ```create order request curl --location 'https://sandbox.juspay.in/ecr/orders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic XXXXXXXXXXXXX' \ --data-raw '{ "order_id": "Ord_1740487604", "amount": "1", "currency": "INR", "customer_id": "cth_x7LiELXbN", "customer_email": "test@email.com", "customer_phone": "999999999", "product_id": "JPP20240911195726", "return_url": "https://juspay.in/", "description": "Description", "gateway_id": "514", "mandate_max_amount": "3", "options.create_mandate": "REQUIRED", "mandate.amount_rule": "VARIABLE", "mandate.frequency":"ONETIME", "mandate.start_date": "1740487604", "mandate.block_fund":"false", "metadata.JUSPAY:gateway_reference_id": "YesbizMandate" }' ``` #### Transaction Request Code Snippet: ```transaction request curl --location 'https://sandbox.juspay.in/txns' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic XXXXXXXXXXXXX' \ --data-urlencode 'order_id=Ord_1740486885' \ --data-urlencode 'merchant_id=mandate_juspay' \ --data-urlencode 'payment_method_type=UPI' \ --data-urlencode 'payment_method=COLLECT' \ --data-urlencode 'upi_vpa=test@ybl' \ --data-urlencode 'should_create_mandate=true' \ --data-urlencode 'redirect_after_payment=true' \ --data-urlencode 'format=json' \ --data-urlencode 'mandate_type=EMANDATE' ``` ### Sample Response: #### Session Response: ```plaintext { "status": "NEW", "id": "ordeh_2c3c923b243f46d485143230b263146c", "order_id": "1740207500", "payment_links": { "web": "https://payments.juspay.in/payment-page/order/ordeh_2c3c923b243f46d485143230b263146c", "expiry": null }, "sdk_payload": { "requestId": "e54f470772b24e49bc29f681082584d7", "service": "in.juspay.hyperpay", "payload": { "mandate.frequency": "ONETIME", "firstName": "John", "mandate.startDate": "1775563443", "clientId": "testMerchant", "customerId": "Customer12345", "orderId": "1740207500", "returnUrl": "https://www.google.com", "currency": "INR", "customerEmail": "TEST@gmail.com", "customerPhone": "9999999999", "service": "in.juspay.hyperpay", "metadata.webhookUrl": "https://payment.testMerchant.com/pages/ProcessJusPayResponse.aspx", "description": "Payment Page", "options.createMandate": "OPTIONAL", "mandate.blockFunds": true, "mandate.revokableByCustomer": false, "mandate.maxAmount": "10000.00", "environment": "production", "lastName": "Wick", "timestamp": "1678343548", "merchantId": "testMerchant", "amount": "9000.0", "clientAuthTokenExpiry": "2025-02-22T07:13:20Z", "clientAuthToken": "tkn_6895f2e50fe74794b6bb43891c33f3ce", "action": "paymentPage", "mandate.endDate": "1782557403" } } } ``` #### Order Response: ```plaintext "res_body": { "order_id": "93293823", "status": "CREATED", "status_id": 1, "id": "ordeh_ejfnwejkfnwejfw", "payment_links": { "mobile": "https://payments.juspay.in/payment-page/order/ordeh_ejfnwejkfnwejfw", "web": "https://payments.juspay.in/payment-page/order/ordeh_ejfnwejkfnwejfw", "iframe": "https://payments.juspay.in/payment-page/order/ordeh_ejfnwejkfnwejfw" } } ``` #### Transaction Response: ```plaintext "res_body": { "txn_id": "merchantID-93293823-1", "order_id": "93293823", "status": "PENDING_VBV", "payment": { "authentication": { "url": "https://api.juspay.in/v2/pay/start/icicipru/mozpodCcaGwgsxgfkvQ?cardIssuerBankName%3DCOLLECT%26cardType%3DUPI%26paymentMethod%3DCOLLECT%26paymentMethodType%3DUPI", "method": "GET" } }, "txn_uuid": "mozpodCcafbjhgbdsfvQ" }, ``` --- ## See Also - [Irrevocable Mandates](https://juspay.io/in/docs/api-reference/docs/express-checkout/irrevocable-mandates) - [Mutual Fund Flow in Mandates](https://juspay.io/in/docs/api-reference/docs/express-checkout/mutual-fund-flow-in-mandates)