JavaScript is disabled. Some features may not work. You can also read the static version: View text version

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.

Request

Response

API Endpoints

Sandbox Link

POST

https://sandbox.juspay.in/txns

Production Link

POST

https://api.juspay.in/txns

                      Basic Auth
                      *
                      

Base64 Encoded Username:Password

Mandatory

Consists of two parts.

Username: API Key obtained from Juspay dashboard
Password: Empty string

Example:- Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==

                      Content-Type
                      
                      

string

application/x-www-form-urlencoded

                      x-merchantid
                      
                      

String

Reecommended

Unique identifier for the merchant. This is the Merchant ID provided by Juspay. The value is case sensitive.

Passing this value will help us route efficiently at network level.

Example:- x-merchantid: testaccount

Body

                      order
                      
                      

object

                      order_id
                      *
                      

string

Mandatory

Unique Identifier for the order.

                      amount
                      *
                      

string

Mandatory

This is the amount that a customer will be charged in this transaction.

                      customer_id
                      *
                      

string

Mandatory

Customer Identifier against which the mandate was created.

                      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 backend 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.

                      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

Line 1 in the billing address

                      billing_address_line2
                      
                      

string

Line 2 in the billing address

                      billing_address_line3
                      
                      

string

Line 3 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

Line 1 in the shipping address

                      shipping_address_line2
                      
                      

string

Line 2 in the shipping address

                      shipping_address_line3
                      
                      

string

Line 3 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

                      udf1
                      
                      

string

                      udf2
                      
                      

string

                      udf3
                      
                      

string

                      udf4
                      
                      

string

                      udf5
                      
                      

string

                      udf6
                      
                      

string

                      udf7
                      
                      

string

                      udf8
                      
                      

string

                      udf9
                      
                      

string

                      udf10
                      
                      

string

                      gateway_id
                      
                      

string

Specify your preferred gateway for this order. Complete mapping for gateway_id can be found here: Gateway mapping

                      merchant_id
                      *
                      

string

Required

The username you hold at Juspay

                      mandate_id
                      *
                      

string

Required

Mandate ID sent by Juspay after successful mandate registration.

                      mandate
                      
                      

object

                      notification_id
                      
                      

string

[CONDITIONAL] The object_reference_id which was sent in notification API call. Applicable only for merchants calling Notification and Execution APIs separately.

                      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

Required

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.

                      format
                      *
                      

string

Required

The format of the response. Should be passed as json.

Response Body

                      txn_uuid
                      
                      

String

Transaction UUID for the payment

                      txn_id
                      
                      

String

Transaction Id for the payment

                      status
                      
                      

String

Status of the transaction. See Appendix for status mapping.

                      payment
                      
                      

Object

                      authentication
                      
                      

Object

url

String

URL to which the user has to be taken to for completing the authentication

                      method
                      
                      

String

HTTP Method for authentication. Can be one of GET or POST

                      payment.authentication.params
                      
                      

Params Object

Present only when the method is POST. Parameter map that has to be sent along with the URL for authentication.

                      order_id
                      
                      

String

Order ID of the transaction

Response Body

                      error_message
                      
                      

String

Provides the reason for the error

Example:- Sample value: Mandate not found

                      status
                      
                      

String

Error status

Example:- invalid_request_error

                      error_code
                      
                      

String

Specifies the Error code

Example:- Sample value: Mandate not found

                      error_info
                      
                      

JSON

Additional information on the error message

                      user_message
                      
                      

String

Error message can be displayed to the user

Example:- Sample value: Cannot process your request as mandate not found.

                      developer_message
                      
                      

String

Detailed info on the error

Example:- Sample value: Mandate not found for customer.

                      category
                      
                      

String

category of the error

Example:- Sample value: USER_ERROR

Error Codes

Scroll inside to view more

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"}