Mandate Execution API

get https://sandbox.juspay.in/txns

Once the Mandate is successfully created, the merchant will receive a mandate_id and 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 charge without a 2nd factor (2FA). This API will an create an order and perform a transaction with PG based on the mandate_id passed in the request.

NOTE:

For recurring mandates, this API is sent only 24 -48 hours after a successful notification response.

Response Parameters for the Mandate Execution API: (click to view)

Note:

This is the same as the Payment Status Object returned for Payments API requests (with two parameters added: txn_uuid and an Offer Details object):

In the redirect response, webhook, and check status API, mandate data will be passed additionally from the current parameters.

Parameter	Type	Description
order_id	String	Unique Identifier for the order.
txn_id	String	Transaction ID for the payment attempt.
txn_uuid	String	Transaction UUID
status	String	Status of the transaction. See Appendix below for status mapping. PENDING_VBV indicates that the transaction requires authentication to complete.
payment:wwwwwwwww {authentication: {...}}	Object	Contains `authentication` object: {`method, url, params`}

Parameters for the payment object:
{click to open)


authentication:wwwwww {method, url, params}	Object	Authentication parametersw

Parameters for the authentication object:
(click to open)

Parameter	Type	Description
method	String	HTTP Method for authentication. Can be one of GET or POST. (For redirection instructions, see the "Handling the Redirection Method" section.)
url	String	URL to which the user has to be taken to for completing the authentication
params	String	Present only when the method is POST. Parameter map that has to be sent along with the URL for authentication. Do not hardcode the params in your client * Never assume that you will receive param “x” or param “y”. This is completely dynamic and will vary on a case by case basis.


offer_details:wwwwwwti {`offers:`[...]}	Array in Object	The mechanism of running offers is the responsibility of merchants in collaboration with PG/Banks (used only for UPI Intent).

APPENDIX - Transaction status codes and meaning:

Status	ID	Meaning
NEW	10	Newly created order
PENDING_VBV	23	Authentication is in progress
CHARGED	21	Successful transaction
AUTHENTICATION_FAILED	26	User did not complete authentication
AUTHORIZATION_FAILED	27	User completed authentication, but bank refused the transaction.
JUSPAY_DECLINED	22	User input is not accepted by the underlying PG.
AUTHORIZING	28	Transaction status is pending from bank.

Mandate Execution API failure responses: (click to view)

Status code	Reason	Response
401	Invalid Authentication	{ "status": "error", "error_code": "access_denied" }
400	Duplicate order id	{ "status_id": 40, "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": "Invalid Request", "error_message": "Amount not found in request.", "error_code": "Invalid" }
400	Order amount greater than mandate max amount	{ "status": "Invalid Request", "error_message": "Order amount greater than mandate max amount ( max amount>).", "error_code": "Invalid" }
400	Order amount not equal to mandate max amount.	{ "status": "Invalid Request", "error_message": "Order amount not equal to mandate max amount (<currency <> max amount>).", "error_code": "Invalid" }
400	Currency not valid for mandate transaction	{ "status": "Invalid Request", "error_message": "currency not valid for mandate transaction.", "error_code": "Invalid" }
400	notification_id not found in request.	{ "status": "Invalid Request", "error_message": "`mandate.notification_id` is mandatory.", "error_code": "Invalid" }
400	Notification record not found	{ "status": "Invalid Request", "error_message": "Notification record not found for ---", "error_code": "Invalid" }
400	Notification status is not successful.	{ "status": "Invalid Request", "error_message": "Notification status is not successful.", "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 non-active (REVOKED / FAILURE) state. Recurring cannot be executed", "error_code": "Mandate is in non-active (REVOKED / FAILURE) state. Recurring cannot be executed" }

⭣

Request Parameters - The request consists of a mandate_id , Order Object, Mandate Object, and other parameters, as listed below:w w w w w (click to open tables)

Note:

Check table here for additional request parameters that may be required depending on the payment gateway or aggregator used on the backend.
(click here to view & move left to right)

Parameter	HDFC	ICICI	Axis	PayU	Citrus	PayTM	EBS	RazorPay	CCAvenue
order_id	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
amount	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
customer_id	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
customer_email	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
customer_phone	Optional	Optional	Optional	Yes	Yes	Yes	Yes	Yes	Yes
description	Optional	Optional	Yes	Yes	Yes	Yes	Yes	Yes	Yes
product_id	No	No	No	No	No	No	No	No	No
billing_address_first_name	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_last_name	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_line1	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_line2	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_line3	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_city	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_state	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_country	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_postal_code	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_phone	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_country_code_iso	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_first_name	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_last_name	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_line1	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_line2	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_line3	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_city	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_state	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_country	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_postal_code	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_phone	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_country_code_iso	No	No	No	Optional	Optional	No	Yes	No	Yes

Field	Type	Description
order:wwwwwwwwwwwt {param1, param2,..,{...}}	Object	Object containing order details

Parameter Groups contained within Order Object:

Order Info Parameters:

Field		Type	Description
order_id	*	String	Unique Identifier for the order. You can pass your native order ID here. it is suggested to keep the order id length as a maximum of 21 characters.
amount	*	String	This is the amount that a customer will be charged in this transaction.
customer_id	*	String	Unique ID for a customer that you get after running the Create Customer API (Check Customer section for more details)
currency		String	ISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: `INR`
customer_email		String	Email address of the customer. This field is mandatory if gateway requires it.
customer_phone		String	Mobile number or fixed line number of the customer. This field is mandatory if gateway requires it.
description		String	Short description for the order. We send this information to the gateways whenever there is a provision for this.
return_url		String	A fully qualified URL such as 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.
product_id		String	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.
metadata: {prm1, prm2,...}		Object	Metadata is used to send custom params to the downstream system, irrespective of default parameters: Example parameters BILLDESK:AdditionalInfo1 String BILLDESK:AdditionalInfo2 String
gateway_id		String	Specify your preferred gateway for this order. Complete mapping for “gateway_id” can be found here: Gateway mapping

* = Required

Billing/Shipping Address Parameters:

Field	Type	Description
billing_address_first_name	String	First name in the billing address
billing_address_last_name	String	Last name in the billing address
billing_address_line1	String	Line1 in the billing address
billing_address_line2	String	Line2 in the billing address
billing_address_line3	String	Line3 in the billing address
billing_address_city	String	Billing address city
billing_address_state	String	Billing address state
billing_address_country	String	Billing address country
billing_address_postal_code	String	Billing address postal code or zip code
billing_address_phone	String	Mobile or phone number in the billing address
billing_address_country_code_iso	String	ISO Country code (Default value: IND)


shipping_address_first_name	String	First name in the shipping address
shipping_address_last_name	String	Last name in the shipping address
shipping_address_line1	String	Line1 in the shipping address
shipping_address_line2	String	Line2 in the shipping address
shipping_address_line3	String	Line3 in the shipping address
shipping_address_city	String	Shipping address city
shipping_address_state	String	Shipping address state
shipping_address_country	String	Shipping address country
shipping_address_postal_code	String	shipping address postal code or zip code
shipping_address_phone	String	Mobile or phone number in the shipping address
shipping_address_country_code_iso	String	ISO Country code (Default value: IND)

UDF Parameters:

udf1 to udf10 - Optional user defined fields which will be echoed back in the response from Juspay with a Max character limit of 255. These fields may be used to pass any additional information that is required to be stored at Juspay for any analysis or other operations. In some cases, these UDFs are passed to the downstream gateways as well.

Field	Type	Description
udf1	String	User Defined Field
udf2	String
udf3	String
udf4	String
udf5	String
udf6	String
udf7	String
udf8	String
udf9	String
udf10	String


mandate:wwwwwwwwwt {param1, param2, ....}	Object Strings	Object containing mandate details

Mandate Object Parameters:

Field	Type	Description
notification_id	String	[CONDITIONAL] The object_reference_id which was sent in notification API call. Applicable only for merchants calling Notification and Execution APIs separatly.
display_invoice_number	String	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.
execution_date	String	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.

Other Parameters sent by API, but not included in a Parameter Group:

Field		Type	Description
merchant_id	*	String	The username you hold at Juspay
mandate_id	*	String	Mandate ID sent by Juspay after successful mandate creation.
format	*	String	The format of the response. Should be passed as `json`.

* = Required