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)
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)
(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 parametersBILLDESK:AdditionalInfo1 StringBILLDESK:AdditionalInfo2 String | |
gateway_id | String | Specify your preferred gateway for this order. Complete mapping for “gateway_id” can be found here: Gateway mapping |
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 . |