Hey! These docs are for version 3.2, which is no longer officially supported. Click here for the latest version, 1.0!

Mandate Execution API

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.
ParameterTypeDescription
order_idStringUnique Identifier for the order.
txn_idStringTransaction ID for the payment attempt.
txn_uuidStringTransaction UUID
statusStringStatus of the transaction. See Appendix below for status mapping. PENDING_VBV indicates that the transaction requires authentication to complete.
payment:wwwwwwwww
    {authentication: {...}}
ObjectContains authentication object:
{method, url, params}
 Parameters for the payment object:
     {click to open)
authentication:wwwwww
    {method, url, params}
ObjectAuthentication parametersw
  Parameters for the authentication object:
      (click to open)
ParameterTypeDescription
methodStringHTTP Method for authentication. Can be one of GET or POST. (For redirection instructions, see the "Handling the Redirection Method" section.)
urlStringURL to which the user has to be taken to for completing the authentication
paramsStringPresent 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:
StatusIDMeaning
NEW10Newly created order
PENDING_VBV23Authentication is in progress
CHARGED21Successful transaction
AUTHENTICATION_FAILED26User did not complete authentication
AUTHORIZATION_FAILED27User completed authentication, but bank refused the transaction.
JUSPAY_DECLINED22User input is not accepted by the underlying PG.
AUTHORIZING28Transaction status is pending from bank.
  Mandate Execution API failure responses:     (click to view)
Status codeReasonResponse
401Invalid Authentication{
"status": "error",
"error_code": "access_denied"
}
400Duplicate order id{
"status_id": 40,
"status": "DUPLICATE_ORDER_ID",
"error_message": "Order already exists with the given order_id"
}
400Invalid order amount{
"status": "Invalid Request",
"error_message": "Invalid order amount",
"error_code": "Invalid"
}
400Mandate max amount not found{
"status": "Invalid Request",
"error_message": "Mandate max amount not found.",
"error_code": "Invalid"
}
400Amount not found in request.{
"status": "Invalid Request",
"error_message": "Amount not found in request.",
"error_code": "Invalid"
}
400Order amount greater than mandate max amount{
"status": "Invalid Request",
"error_message": "Order amount greater than mandate max amount ( max amount>).",
"error_code": "Invalid"
}
400Order 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"
}
400Currency not valid for mandate transaction{
"status": "Invalid Request",
"error_message": "currency not valid for mandate transaction.",
"error_code": "Invalid"
}
400notification_id not found in request.{
"status": "Invalid Request",
"error_message": "mandate.notification_id is mandatory.",
"error_code": "Invalid"
}
400Notification record not found{
"status": "Invalid Request",
"error_message": "Notification record not found for ---",
"error_code": "Invalid"
}
400Notification status is not successful.{
"status": "Invalid Request",
"error_message": "Notification status is not successful.",
"error_code": "Invalid"
}
400Mandate not found{
"status": "invalid_request_error",
"error_message": "Mandate not found",
"error_code": "Mandate not found"
}
400Mandate 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)
ParameterHDFCICICIAxisPayUCitrusPayTMEBSRazorPayCCAvenue
order_idYesYesYesYesYesYesYesYesYes
amountYesYesYesYesYesYesYesYesYes
customer_idYesYesYesYesYesYesYesYesYes
customer_emailYesYesYesYesYesYesYesYesYes
customer_phoneOptionalOptionalOptionalYesYesYesYesYesYes
descriptionOptionalOptionalYesYesYesYesYesYesYes
product_idNoNoNoNoNoNoNoNoNo
billing_address_first_nameNoNoNoOptionalOptionalNoYesNoYes
billing_address_last_nameNoNoNoOptionalOptionalNoYesNoYes
billing_address_line1NoNoNoOptionalOptionalNoYesNoYes
billing_address_line2NoNoNoOptionalOptionalNoYesNoYes
billing_address_line3NoNoNoOptionalOptionalNoYesNoYes
billing_address_cityNoNoNoOptionalOptionalNoYesNoYes
billing_address_stateNoNoNoOptionalOptionalNoYesNoYes
billing_address_countryNoNoNoOptionalOptionalNoYesNoYes
billing_address_postal_codeNoNoNoOptionalOptionalNoYesNoYes
billing_address_phoneNoNoNoOptionalOptionalNoYesNoYes
billing_address_country_code_isoNoNoNoOptionalOptionalNoYesNoYes
shipping_address_first_nameNoNoNoOptionalOptionalNoYesNoYes
shipping_address_last_nameNoNoNoOptionalOptionalNoYesNoYes
shipping_address_line1NoNoNoOptionalOptionalNoYesNoYes
shipping_address_line2NoNoNoOptionalOptionalNoYesNoYes
shipping_address_line3NoNoNoOptionalOptionalNoYesNoYes
shipping_address_cityNoNoNoOptionalOptionalNoYesNoYes
shipping_address_stateNoNoNoOptionalOptionalNoYesNoYes
shipping_address_countryNoNoNoOptionalOptionalNoYesNoYes
shipping_address_postal_codeNoNoNoOptionalOptionalNoYesNoYes
shipping_address_phoneNoNoNoOptionalOptionalNoYesNoYes
shipping_address_country_code_isoNoNoNoOptionalOptionalNoYesNoYes
FieldTypeDescription
order:wwwwwwwwwwwt
      {param1, param2,..,{...}}
ObjectObject containing order details
Parameter Groups contained within Order Object:
  Order Info Parameters:
FieldTypeDescription
order_id*StringUnique 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*StringThis is the amount that a customer will be charged in this transaction.
customer_id*StringUnique ID for a customer that you get after running the Create Customer API (Check Customer section for more details)
currencyStringISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: INR
customer_emailStringEmail address of the customer.
This field is mandatory if gateway requires it.
customer_phoneStringMobile number or fixed line number of the customer.
This field is mandatory if gateway requires it.
descriptionStringShort description for the order. We send this information to the gateways whenever there is a provision for this.
return_urlStringA 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_idStringAn 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,...}
ObjectMetadata is used to send custom params to the downstream system, irrespective of default parameters:
 Example parameters
BILLDESK:AdditionalInfo1
    String
BILLDESK:AdditionalInfo2
    String
gateway_idStringSpecify your preferred gateway for this order. Complete mapping for “gateway_id” can be found here: Gateway mapping
* = Required
  Billing/Shipping Address Parameters:
FieldTypeDescription
billing_address_first_nameStringFirst name in the billing address
billing_address_last_nameStringLast name in the billing address
billing_address_line1StringLine1 in the billing address
billing_address_line2StringLine2 in the billing address
billing_address_line3StringLine3 in the billing address
billing_address_cityStringBilling address city
billing_address_stateStringBilling address state
billing_address_countryStringBilling address country
billing_address_postal_codeStringBilling address postal code or zip code
billing_address_phoneStringMobile or phone number in the billing address
billing_address_country_code_isoStringISO Country code
(Default value: IND)
shipping_address_first_nameStringFirst name in the shipping address
shipping_address_last_nameStringLast name in the shipping address
shipping_address_line1StringLine1 in the shipping address
shipping_address_line2StringLine2 in the shipping address
shipping_address_line3StringLine3 in the shipping address
shipping_address_cityStringShipping address city
shipping_address_stateStringShipping address state
shipping_address_countryStringShipping address country
shipping_address_postal_codeStringshipping address postal code or zip code
shipping_address_phoneStringMobile or phone number in the shipping address
shipping_address_country_code_isoStringISO 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.
FieldTypeDescription
udf1StringUser Defined Field
udf2String
udf3String
udf4String
udf5String
udf6String
udf7String
udf8String
udf9String
udf10String
mandate:wwwwwwwwwt
      {param1, param2, ....}
Object
Strings
Object containing mandate details
    Mandate Object Parameters:
FieldTypeDescription
notification_idString[CONDITIONAL] The object_reference_id which was sent in notification API call. Applicable only for merchants calling Notification and Execution APIs separatly.
display_invoice_numberStringApplicable 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_dateStringApplicable 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:
FieldTypeDescription
merchant_id*StringThe username you hold at Juspay
mandate_id*StringMandate ID sent by Juspay after successful mandate creation.
format*StringThe format of the response. Should be passed as json.
  * = Required
Language
Authentication
Basic
base64
:
Click Try It! to start a request and see the response here!