--- page_source: https://juspay.io/sea/docs/hyper-checkout-sea/web/mandates/mandate-execution-api page_title: Mandate Execution API --- ## API Version: default # Mandate Execution API After the successful Mandate registration, Merchant will receive a mandate_id, mandate_token from Juspay that should be stored against a customer at their end. For the subsequent charge transactions, the merchant is supposed to pass a combination of customer_id and mandate_id to do a debit without a 2FA. This API will create an order and perform a transaction with PG based on the mandate_id passed in the request. ## Endpoints: - Sandbox: https://sandbox.juspay.in/txns - Production: https://api.juspay.in/txns ## Request Type: POST ## Authorization: #### Basic Auth: Consists of two parts. * Username: API Key obtained from Juspay dashboard * Password: Empty string Example:- Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg== - Tags: Base64 Encoded Username:Password, Mandatory ## Headers: #### Content-Type: application/x-www-form-urlencoded - Tags: string #### x-merchantid: Unique identifier for the merchant. This is the Merchant ID provided by Juspay. The value is case sensitive. > **Note** > Passing this value will help us route efficiently at network level. - Value: x-merchantid: testaccount - Tags: String, Reecommended ## Sample Code Snippets: ### Sample Request: #### Request Code Snippet: ```request curl -X POST 'https://api.juspay.in/txns' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: Basic '\ -H 'x-merchantid: your_merchant_id' \ -d 'order.order_id=26234761248249834753485721' \ -d 'order.amount=1.00' \ -d 'order.currency=USD'\ -d 'order.customer_id=cst_lz7zmpemoo5okgav' \ -d 'mandate_id=4rKxSj3bNXs7RQcdtajAkb' \ -d 'mandate.execution_date=1622369936' \ -d 'merchant_id=merchantid' \ -d 'format=json' ``` ### Sample Response: #### 200 - Success: ```plaintext { "payment": { "authentication": { "method": "GET", "url": "https://api.juspay.in/v2/pay/finish/Merchant/mozpdRvuvTaZmey4DUM/26234761248249834753485721" } }, "status": "CHARGED", "txn_uuid": "mozpdRvuvTaZmey4DUM", "offer_details": { "offers": [] }, "order_id": "26234761248249834753485721", "txn_id": "Merchant-26234761248249834753485721-1" } ``` #### 400 - Bad Request: ```plaintext { "error_message": "Mandate not found", "status": "invalid_request_error", "error_code": "Mandate not found", "error_info": { "user_message": "Cannot process your request as mandate not found.", "developer_message": "Mandate not found for customer.", "code": "RESOURCE_NOT_FOUND", "category": "USER_ERROR" } } ``` ## Body Parameters: ### Parameters: #### order: - Value: - **Order_id**: - Description: Unique Identifier for the order. - Tags: string, Mandatory - **Amount**: - Description: This is the amount that a customer will be charged in this transaction. - Tags: string, Mandatory - **Customer_id**: - Description: Customer Identifier against which the mandate was created. - Tags: string, Mandatory - **Currency**: - Description: ISO string of the currency. Use **INR** for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: `INR` - Tags: string - **Customer_email**: - Description: Email address of the customer. This field is **mandatory** if gateway requires it. - Tags: string - **Customer_phone**: - Description: Mobile number or fixed line number of the customer. This field is **mandatory** if gateway requires it. - Tags: string - **Description**: - Description: Short description for the order. We send this information to the backend gateways whenever there is a provision for this. - Tags: string - **Return_url**: - Description: A fully qualified URL such as [http://shop.merchant.com/](http://shop.merchant.com/) to which the customer will be redirected after payment completion.This URL shouldn’t contain any **query parameters** .This URL takes higher precedence over the common return URL configured in your account settings. - Tags: string - **Product_id**: - Description: An identifier for the product on the **Lender** side for which the payment is being done. This field is just echoed back in the response so that **Lender** can differentiate on their side. - Tags: string - **Billing_address_first_name**: - Description: First name in the billing address - Tags: string - **Billing_address_last_name**: - Description: Last name in the billing address - Tags: string - **Billing_address_line1**: - Description: Line 1 in the billing address - Tags: string - **Billing_address_line2**: - Description: Line 2 in the billing address - Tags: string - **Billing_address_line3**: - Description: Line 3 in the billing address - Tags: string - **Billing_address_city**: - Description: Billing address city - Tags: string - **Billing_address_state**: - Description: Billing address state - Tags: string - **Billing_address_country**: - Description: Billing address country - Tags: string - **Billing_address_postal_code**: - Description: Billing address postal code or zip code - Tags: string - **Billing_address_phone**: - Description: Mobile or phone number in the billing address - Tags: string - **Billing_address_country_code_iso**: - Description: ISO Country code. Default value: **IND** - Tags: string - **Shipping_address_first_name**: - Description: First name in the shipping address - Tags: string - **Shipping_address_last_name**: - Description: Last name in the shipping address - Tags: string - **Shipping_address_line1**: - Description: Line 1 in the shipping address - Tags: string - **Shipping_address_line2**: - Description: Line 2 in the shipping address - Tags: string - **Shipping_address_line3**: - Description: Line 3 in the shipping address - Tags: string - **Shipping_address_city**: - Description: Shipping address city - Tags: string - **Shipping_address_state**: - Description: Shipping address state - Tags: string - **Shipping_address_country**: - Description: Shipping address country - Tags: string - **Shipping_address_postal_code**: - Description: Shipping address postal code or zip code - Tags: string - **Shipping_address_phone**: - Description: Mobile or phone number in the shipping address - Tags: string - **Shipping_address_country_code_iso**: - Description: ISO Country code. Default value: **IND** - Tags: string - **Udf1**: - Tags: string - **Udf2**: - Tags: string - **Udf3**: - Tags: string - **Udf4**: - Tags: string - **Udf5**: - Tags: string - **Udf6**: - Tags: string - **Udf7**: - Tags: string - **Udf8**: - Tags: string - **Udf9**: - Tags: string - **Udf10**: - Tags: string - **Gateway_id**: - Description: Specify your preferred gateway for this order. Complete mapping for **gateway_id** can be found here: [Gateway mapping](/resources-global/docs/dynamic-routing/dynamic-routing#Enforce-Gateway-Routing) - Tags: string - Tags: object #### merchant_id: - Description: The username you hold at Juspay - Tags: string, Required #### mandate_id: - Description: Mandate ID sent by Juspay after successful mandate registration. - Tags: string, Required #### mandate: - Value: - **Notification_id**: - Description: [CONDITIONAL] The object_reference_id which was sent in notification API call. Applicable only for merchants calling Notification and Execution APIs separately. - Tags: string - **Display_invoice_number**: - Description: Applicable only for cards SI. If merchant wants to generate invoice display number, but wants Juspay to handle pre-debit notification, this needs to be sent. - Tags: string - **Execution_date**: - Description: Applicable only for merchants enabled for mandate workflow (notification + execution flow).UNIX EPOCH timestamp format. Default execution happens at 25th hour of successful notification. If a merchant wants to execute mandate at custom time anytime after 25th hour, send execution_date. - Tags: string, Required - Tags: object #### format: - Description: The format of the response. Should be passed as json. - Tags: string, Required ## API Responses: ### 200: #### txn_uuid: - Description: Transaction UUID for the payment - Tags: String #### txn_id: - Description: Transaction Id for the payment - Tags: String #### status: - Description: Status of the transaction. See Appendix for status mapping. - Tags: String #### payment: - Value: - **Authentication**: - Value: - **Url**: - Description: URL to which the user has to be taken to for completing the authentication - Tags: String - **Method**: - Description: HTTP Method for authentication. Can be one of GET or POST - Tags: String - **Payment.authentication.params**: - Description: Present only when the method is POST. Parameter map that has to be sent along with the URL for authentication. - Tags: Params Object - Tags: Object - Tags: Object #### order_id: - Description: Order ID of the transaction - Tags: String ### 400: #### error_message: - Description: Provides the reason for the error - Value: Sample value: Mandate not found - Tags: String #### status: - Description: Error status - Value: invalid_request_error - Tags: String #### error_code: - Description: Specifies the Error code - Value: Sample value: Mandate not found - Tags: String #### error_info: - Description: Additional information on the error message - Value: - **User_message**: - Description: Error message can be displayed to the user - Value: Sample value: Cannot process your request as mandate not found. - Tags: String - **Developer_message**: - Description: Detailed info on the error - Value: Sample value: Mandate not found for customer. - Tags: String - **Category**: - Description: category of the error - Value: Sample value: USER_ERROR - Tags: String - Tags: JSON ## Error Codes | Error Codes | Description | Sample Error Message | |---|---|---| | 401 | Invalid Authentication | { "status": "error", "error_code": "access_denied" } | | 400 | Duplicate order id | { "status": "DUPLICATE_ORDER_ID", "error_message": "Order already exists with the given order_id" } | | 400 | Invalid order amount | {"status":"Invalid Request","error_message":Invalid order amount","error_code":"Invalid"} | | 400 | Mandate max amount not found | {"status":"Invalid Request","error_message":"Mandate max amount not found.","error_code":"Invalid"} | | 400 | Amount not found in request. | {"status":"ERROR","error_message":"Bad request.","error_code":"Bad request."} | | 400 | Order amount greater than mandate max amount | {"status":"Bad Request","error_message":"Order amount greater than mandate max amount (<="" style="user-select: text;">max amount>)","error_code":"Invalid"} | | 400 | Currency not valid for mandate transaction | {"status":"Bad Request","error_message":"currency not valid for mandate transaction.","error_code":"Invalid"} | | 400 | Mandate not found | {"status":"invalid_request_error","error_message":"Mandate not found","error_code":"Mandate not found"} | | 400 | Mandate not in active state | {"status":"invalid_request_error","error_message":"Mandate is in PAUSED state. Recurring cannot be executed","error_code":"invalid_request"} | | 404 | Passing Invalid URL | - | | 400 | Not passing merchant_id field | {"error_message":"Bad request.","status":"ERROR","error_code":"Bad request.","error_info":{"user_message":"Bad request.","fields":[{"field_name":"merchant_id","reason":"Field required but not passed."}],"developer_message":"Failed while parsing your request.","code":"MISSING_MANDATORY_PARAMETER","category":"USER_ERROR"}} | | 400 | Invalid Merchant ID | {"user_message":"Invalid merchant id. Cannot process your request.","error_message":"Invalid Request","error":true,"error_info":{"user_message":"Please pass valid merchant_id in request.","fields":[{"field_name":"merchant_id","reason":"Invalid merchant_id."}],"developer_message":"merchant_id is invalid.","code":"RESOURCE_NOT_FOUND","category":"USER_ERROR"}} | | 400 | Perfroming a transaction by providing a different currency than the create mandate | {"error_message":"currency not valid for mandate transaction","status":"Bad Request","error_code":"Invalid","error_info":{"user_message":"Invalid request params. Please verify your input.","developer_message":"currency not valid for mandate transaction","code":"INVALID_INPUT","category":"USER_ERROR"}} | | 200 | Passing invalid customer_id | {"payment":{"authentication":{"method":"GET","url":"https://sandbox.juspay.in/v2/pay/finish/Merchant/mozsgdGv78wAz8dpfz/1738237998"}},"status":"AUTHENTICATION_FAILED","txn_uuid":"mozsdGvg78wAz8dpfz","resp_message":"{\"status\":422,\"errorCode\":\"800\",\"message\":\"Contract not found\",\"errorType\":\"validation\",\"pspReference\":\"QV5HW3RDKLSMC375\"}","resp_code":"FAILURE_RESPONSE","offer_details":{"offers":[]},"order_id":"1738237998","txn_id":"Merchant-1738237998-1"} |