Overview of the Mandates APIs

For some purchases, customers have the option to make payments that are either one time or recurring in nature, for e.g. utility bills payment, insurance premium etc. If the recurring method is chosen, a mandate can be created that includes mechanisms for billing frequency, pre-notifications, start/end date, rules for debit amount, pause, revoke, modify, etc. Mandates can be initiated by either the payer or payee. If initiated by payee, payer has the option of approving or rejecting the mandate request. Once a mandate is created, it will allow the user’s account to be debited as per the agreed terms and conditions, without requiring the user to authenticate the transaction every time.

The following Mandate APIs will handle all mandate-related interactions and transactions on the Juspay server. These APIs are similar to Order APIs, except that a Mandate Object is included that contains a Mandate ID, and rules for debit amount , frequency, etc.

Flow diagrams for Mandate APIs:

MandateFlow6

Note:

The Get Mandate Order Status API is used to fetch the order (registration) status of a mandate, but can also be used to check the status of a previously initiated execution of a mandate.

Brief description of each Mandate API:

Create Mandate
Order:

Use this API to create a mandate for your existing customers with subscription specific details like amount, subscription frequency, duration of the mandate, etc. Use mandate_id from the response of this API to call the Mandate Registration API. Prerequisite for creating a mandate is to have the customer already registered/created with you.

POST https://api.juspay.in/orders

Get Mandate
Order Status:

This is very similar to the Get Order Status API, except that it includes a Mandate Object in the response, which provides order status and details of a mandate.

GET https://api.juspay.in/orders/:order_id

Mandate
Registration:

Use this API to choose the preferred mode of payment for the mandate. Supported payment method types include UPI, Card, Wallet and Net banking. Flow diagrams for the COLLECT and PAY payment methods are shown below. The same API will also validate the payment method specific data like UPI, VPA, etc. Share the URL that you get in the response body with your end customer, for whom this mandate is being initiated. They will have to run the same to authorize the collect request from their UPI App.

POST https://api.juspay.in/txns

Notification:

Notification API is required for merchants to notify users. Sends a notification to the customer before the mandate transaction is exercised. A notification must be sent to the user 24 to 48 hours before a Mandate Execution API for recurring mandates. Mandate is executed only if notification is successful.

POST https://api.juspay.in/mandates/:mandate_id

Notification
Status:

Merchants can call this API to check whether a notification has been sent to a customer or not. References a previous notification by object_reference_id.

GET https://api.juspay.in/notifications/:object_reference_id

Mandate
Execution:

After the Mandate is successful, Merchant will receive a mandate_token from Juspay that should be stored against a customer at their end. From the subsequent charge transactions, Merchant is supposed to pass a combination of customer_id and mandate_token / mandate_id to do a charge without a 2nd factor. This API will create the order and will charge it based on the mandate_token or mandate_id passed by the merchant. Must be sent after 24 hours and before 48 hours once a successful notification response is received.

Required: mandate_id, merchant_id, format

Optional: Order Object, Mandate Object: (notification_id,

display_invoice_number, execution_date)

Returns: Payment Status Object

(Request must pass through Acquirer / NPCI / Issuer before response is received.)

GET https://api.juspay.in/txns

List Mandate:

A merchant can call this API to get a detailed list of all the mandates that a customer has with them. The list will also include all revoked, expired, and failed mandates.

GET https://api.juspay.in/customers/:customer_id/mandates

Revoke Mandate:

Use this API to revoke/cancel an already existing mandate by passing the mandate_id.

POST https://api.juspay.in/mandates/:mandate_id

Pause Mandate:

Use this API to pause an active mandate by passing the mandate_id.

Required: mandate_id, command = "pause", merchant_id

Optional: pause_start_date, pause_end_date

Returns: Mandate Object (with pause start/stop times)

POST https://sandbox.juspay.in/mandates/:mandate_id

Resume Mandate:

Use this API to resume a paused mandate by passing the mandate_id.

Required: mandate_id, command = "resume", merchant_id

Optional: resume_date

Returns: Mandate Object (with pause start/stop times)

POST https://sandbox.juspay.in/mandates/:mandate_id

Request Parameters for Mandate APIs

URL Embedded (Path) Parameters:

Field	Type	*	Description
order_id	String	*	Required only for the Get Mandate Order Status API. - Unique Identifier for the order.
mandate_id	String	*	Required only for the Notification API, and the Revoke, Pause, and Resume Mandate APIs. - The Mandate ID sent by Juspay after mandate creation. Mandate ID will be available in the mandate JSON block of Get Mandate Order Status API response.
customer_id	String	*	Required only for the List Mandate API. - Unique ID for a customer.
object_reference_id	String	*	Required only for the Notification Status API. - This is the merchant's unique Identifier for the notification request, and is available in the response body of the Notification API.

* = Required only for the specified APIs

Header:

Field	Type	*	Description
x-merchantid	String	*	Required only for the Create Mandate Order, Get Mandate Order Status, Revoke Mandate, Pause Mandate, and Resume Mandate APIs. - Merchant ID which would have been issued while registering with Juspay

* = Required only for the specified APIs

Objects and Parameter Groups used for Mandate API requests:

(Open tables to view parameters.)

Objects:

Mandate Object Parameters:

- Used only for the Create Mandate Order API.

Field Type Description

max_amount * String Maximum amount for a mandate. Mandatory only if mandate.amount_rule = VARIABLE.

amount_rule String Data type ENUM
Possible values: FIXED, VARIABLE.
By Default it is considered as VARIABLE.
In case of FIXED, max amount will be equal to amount

start_date * String Mandate start date in UNIX EPOCH timestamp (UTC timezone). In case of UPI mandate, the start date has to be today’s date. Mandatory only for UPI Mandate

end_date * String Mandate end date in UNIX EPOCH timestamp (UTC timezone), from when a mandate will move to EXPIRED state and recurring mandate will not be allowed. Mandatory only for UPI Mandate.

block_funds Boolean Set to TRUE if funds have to be blocked while a mandate is being created. Should be TRUE for ONETIME and FALSE for Recurring. By default value will be TRUE for ONETIME and FALSE for Recurring.

frequency

String

Defines the frequency of mandate execution, or how often a customer should be charged.

Description for mandate.frequency

Possible values (ENUM format):

ONETIME, DAILY, WEEKLY, FORTNIGHTLY, MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED

Default: ASPRESENTED

Check here for additional rules on this value.

rule_value

String

Determines the day of week or month that a mandate will be executed, depending on the mandate.frequency.

Description for rule.value

Possible values (Integer format):

1-7	when frequency is WEEKLY. In weekly, serial numbers start from Monday. Monday represents 1 and Sunday represents 7.
1-16	when frequency is FORTNIGHTLY. This mandate is executed twice a month. First day of the month is represented by value ‘1’ and ends with ‘15’ on 15th day of the month. Then again starts with ‘1’ for 16th of the month and ends with the last day of the month.
1-31	when frequency is MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, orYEARLY.

Not required when frequency is ONETIME, DAILY, or ASPRESENTED. For Razorpay, rule_value will be considered as the last date of the week/month/year. For Paytm, rule_value will be considered as today’s date/day.

Check here for additional rules on this value.

rule_type String ON / BEFORE / AFTER
For Razorpay, rule_type will be updated to BEFORE.
For Paytm, rule_type will be updated to AFTER


revokable_by_customer	Boolean	If FALSE, the mandate cannot be revoked by the customer once set. Applicable only for UPI mandate. It should be TRUE for Recurring and TRUE/FALSE for ONETIME. By default, value will be TRUE

* = Required

Metadata Object Parameters:

- Used only for the Create Mandate Order API.

Field		Type	Description
bank_account_number	w	String	Bank account number of VPA used. Used only if downstream supports third party validation.
bank_ifsc		String	IFSC code for a given bank.
PAYTM_V2: SUBSCRIPTION_GRACE_DAYS		String	Number of days after renewal cycle start date for which merchant can send renewal request. By default 0 for DAILY and ASPRESENTED and 7 for remaining frequencies.
PAYTM_V2: SUBSCRIPTION_RETRY_COUNT		String	Applicable only for Paytm. By default 2 for UPI mandate.
PAYTM_V2: GATEWAY_REFERENCE_ID		String	Customized PAYTM_V2 parameter for the payment aggregators. This was found in request, but not in parameter list.

* = Required

Options Object Parameter:

- Used only for the Create Mandate Order API.

Field		Type	Description
create_mandate	*	String	Merchants who want to set up mandates can pass this as either “REQUIRED” or “OPTIONAL”. “REQUIRED” means that the transaction for this order has to be definitely converted to a mandate. “OPTIONAL” means that the final decision of conversion of the transaction lies at the /txns api call with the flag “should_create_mandate”

* = Required

Source Info Object Parameters:

- Used only for the Notification API.

Field		Type	Description
amount	*	String	Amount for which notification is to be sent to customer I.e. "100.00"
txn_date	*	String	Date on which debit is intended to happen in UNIX EPOCH timestamp (UTC timezone) format

* = Required

Parameter Groups:

Order Info Parameters Parameters:

- Used only for the Create Mandate Order and Mandate Execution API.

Field		Type	Description
order_id	*	String	Unique Identifier for the order. You can pass your native order ID here.
amount	*	String	Amount that the customer has to pay. Will accept double values with upto two decimal places. For example, 100.15 is valid, but 100.1532 is not valid.
order_type		String	Set to “TPV_PAYMENT” if using Third-Party Validation.
currency	*	String	ISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: INR
customer_id	*	String	Unique ID for a customer that you get after running the Create Customer API (Check Customer section for more details)
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. Fits well for impulse purchase usecases.
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:

- Used only for the Create Mandate Order and Mandate Execution API.

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:

- Used only for the Create Mandate Order and Mandate Execution API.

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

Payment Method Parameters:

- Used only for the Mandate Registration API.

Note:

These are the same Payment Method Parameters used in the Payments API requests.

Field		Type	Description
order_id	*	String	Unique Identifier for the order.
merchant_id	*	String	ID of the merchant_account that you hold with us.
payment_method_type	*	String	Payment method type of transaction. Possible values: UPI / NB / CARD / WALLET / AADHAAR For eNACH, authentication verification can be done via CARD, NB & AADHAAR (Note: NB eMandate supports only NB login authentication. Banks live with NB eMandate are HDFC (Register + Debit), ICICI (Register + Debit), SBI (Register only) and Axis (Register only)) Banks live with eNACH for NB, CARD and AADHAAR authentication https://www.npci.org.in/PDF/nach/live-members-e-mandates/Live-Banks-in-API-E-Mandate.pdf
payment_method	*	String	Payment method of transaction. COLLECT - For UPI Collect transaction. PAY - For UPI_PAY transaction. For card mandate - One of VISA/MASTERCARD/MAESTRO/AMEX/RUPAY. This is usually inferred from the card number itself and we will take care of this if you are unable to provide this from your end. Please refer to /paymentmethods API https://developer.juspay.in/reference/payment-methods for EMANDATE payment_method values.
redirect_after_payment	*	Boolean	We recommend that you set this to `true` and use the redirection flow. If set to `true`, then the user is redirected to the `return_url` configured for the order. If set to `false`, then the user will be stopped at the response page from the gateway. Your client should be able to read the page/title to infer that the user has completed the transaction.
format	*	String	If it is set to JSON, then the response will be HTTP 200 with a JSON formatted text. Otherwise, the response is HTTP 302 with the Location attribute having the destination URL.

* = Required

Bank Details Parameters:

- Used only for the Mandate Registration API.

Field		Type	Description
bank_name		String	Name of bank that is holding the account
bank_account_number	*	String	Bank account number. Required for emandate/e-NACH, or when `mandate_type`= EMANDATE.
bank_beneficiary_name		String	Account holder name. Should contain alphabetical characters only. Required for emandate/e-NACH, or when `mandate_type`= EMANDATE.
bank_ifsc		String	Bank IFSC. Required for emandate/e-NACH, or when `mandate_type`= EMANDATE.

Card Data Parameters:

- Used only for the Mandate Registration API.

Note:

These are the same Card Data Parameters used in the Payments API requests.

Field		Type	Description
card_token	*	string	A valid card token obtained using /card/list API. If you send this parameter, then `card_number, name_on_card, card_exp_year,` and `card_exp_month` fields are not required. If the token is generated using the /card/tokenize API, `card_number, name_on_card, card_exp_year, card_exp_month,` and `card_security_code` fields are not required. Can only be used when `mandate_type`= MANDATE for a stored card.
card_number		String	A valid credit/debit card number. Required when `mandate_type`= MANDATE for a new card transaction.
card_exp_year		String	Represent the expiry year of the card as YY (two digits only). Required when `mandate_type`= MANDATE for a new card transaction.
card_exp_month		String	Represent the expiry month of the card as MM (two digits only). Required when `mandate_type`= MANDATE for a new card transaction.
card_security_code		String	CVV of the card. Usually three digits. Required when `mandate_type`= MANDATE for a new card transaction.
name_on_card		String	Card holder name. Should contain alphabetical characters only. Required when `mandate_type`= MANDATE for a new card transaction.
save_to_locker		String	This is a boolean variable and accepts true/false. If set to true, then the card will be saved in locker when the transaction is successful. Else, the card will not be saved.

Other Request (Form) Parameters sent by Mandate APIs, but not included in an Object or Parameter Group: (Open tables to view parameters.)

Other request parameters for the Mandate Registration API:

Parameter		Type	Description
upi_vpa	*	String	VPA to which the collect request must be sent
mandate type	*	String	EMANDATE in case of UPI/NB/Wallet. MANDATE in case of card.
should_create_mandate		Boolean	This is a customer’s consent flag. This should be always be TRUE in case of a mandate transaction.

Other request parameters for the Notification API:

Parameter		Type	Description
command	*	String	Set to “pre_debit_notify” for sending notification before execute mandate.
object_reference_id	*	String	Merchants unique Identifier for the request.
description	*	String	Reason for debit that will be sent to user. Max Length: 50
metadata		String	For future use case
mandate: {display_invoice_number}		Object String	If merchant wants to generate invoice display number, this needs to be passed in notification call. If not passed, Juspay will create a unique invoice number and pass it to downstream system. It should be alphanumeric and length upto 25 characters. (Applicable only for cards SI)

Other request parameters for the Mandate Execution API:

Parameter		Type	Description
mandate_id	*	String	Mandate ID sent by Juspay after mandate creation.
merchant_id	*	String	The username you hold at Juspay
format	*	String	The format of the response. Should be passed as `json`.
mandate.notification_id		Object String 1	[CONDITIONAL] The object_reference_id which was sent in notification API call. Applicable only for merchants calling Notification and Execution APIs separatly.
mandate.display_invoice_number		Object String 2	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.
mandate.execution_date		Object String 3	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 request parameters for the Revoke Mandate API:

Parameter		Type	Description
command	*	String	To be set as "revoke" to revoke an existing mandate

Other request parameters for the Pause Mandate API:

Parameter		Type	Description
command	*	String	To be set as "pause", to pause an active mandate
pause_start_date		String	Date in UNIX EPOCH timestamp (UTC timezone) format, when the mandate will be paused. Default value can be the current date.
pause_end_date		String	Date in UNIX EPOCH timestamp (UTC timezone) format, when the mandate status will be automatically changed to ACTIVE. Default value can be set to mandate_end_date.

Other request parameters for the Resume Mandate API:

Parameter		Type	Description
command	*	String	To be set as "resume" to resume a paused mandate
resume_date		String	[Optional] Date in UNIX EPOCH timestamp (UTC timezone) format, when the mandate needs to be set active. Default value will be the current date.

* = Required

Response Parameters for Mandate APIs:

(Click to open tables.)

Status, Redirect Info Object

- Response for the Create Mandate Order API.

Note:

Response parameters are the same as for the Create Order API (Status, Redirect Info).

Parameter	Type	Description
id	String	Unique ID generated by Juspay for the given order.
order_id	String	Given order ID.
status	String	Status of the order. If you receive “NEW”, then the mandate is successfully created. See Appendix below for status mapping. If you invoke this API with an `order_id` which already has a mandate created, then this API will return the result of the Get Mandate Order Status API.
status_id	Integer	Status ID is a numeric ID corresponding to the status value. See Appendix below for code meaning.
payment_links:wwwwwwni {web, mobile, iframe}	Object String	Three links for a Desktop , Mobile, and iFrame checkout screen for the given order (Parameters listed in table below - click to open)

Payment Links Object Parameters:

Field	Type	Description
web	String	Link to checkout page that is optimized for Desktop for the given order.
mobile	String	Link to Mobile optimized checkout page for the given order.
iframe	String	Link to iFrame checkout screen. This is typically embedded inside of your own page.

Payment Links
Order create response now has payment links for web, mobile & iFrame. These links can directly be emailed or messaged to your customers. They will be redirected using a link to enter payment information. If you wish to use your own branding, then you can embed the iframe link into your page. Note that, these links are not valid perpetually. As soon as your order expires (this can be changed via our dashboard), the link will cease to work.

APPENDIX Order status codes and meaning

Status	ID	Meaning
NEW	10	Newly created mandate
PENDING_VBV	23	Authentication is in progress. The customer has to approve the mandate through the PSP App of their choice.
CHARGED	21	Successful transaction. The subscription cost of the period has been charged.
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

Order Object, which includes a Mandate Object

- Response for the Get Mandate Order Status

This response is similar to the Order Object returned for the Get Order Status API, except that it includes a Mandate Object. All objects contained within the Order Object are listed above table:

Parameter	Type	Description
mandate:wwwwwwwwwwwn {param1, param2, ....}	Object String	Object containing mandate details. (Parameters listed in table below - click to open)

Mandate Object Parameters:

Field Type Description

mandate_id String Mandate ID is a unique identifier generated and sent by Juspay after mandate creation. Must be sent with Notification, Revoke Mandate, and Mandate Execution APIs.

mandate_token String Mandate token is a unique identifier generated and sent by Juspay after mandate creation for one-time use. This is a 32 digit alphanumeric unique value. Allows a charge without a 2nd factor.

mandate_status String Current status of the mandate. Must be one of the states listed in this table:
(ENUM format) CREATED / ACTIVE / PAUSED / REVOKED / FAILURE / PENDING / EXPIRED

mandate_type String EMANDATE in case of UPI/NB/Wallet payment
MANDATE in case of Card payment

max_amount String Maximum amount for a mandate. Mandatory only if mandate.amount_rule = VARIABLE.

currency String ISO string of the currency. Default value: INR (Indian Rupee). Among other accepted values are EUR, USD, GBP.

activated_at String Time stamp of mandate activation
This should be included also.

frequency

String

Defines the frequency of mandate execution, or how often a customer should be charged.

Description for mandate.frequency

Possible values (ENUM format):

ONETIME, DAILY, WEEKLY, FORTNIGHTLY, MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED

Default: ASPRESENTED

Check here for additional rules on this value.

amount_rule String Data type ENUM
Possible values: FIXED, VARIABLE.
By Default, it is considered as VARIABLE.
In case of FIXED, max amount will be equal to amount

start_date String Mandate start date in UNIX EPOCH timestamp (UTC timezone). In case of UPI mandate, the start date has to be today’s date. Mandatory only for UPI Mandate.

end_date String Mandate end date in UNIX EPOCH timestamp (UTC timezone), from when a mandate will move to EXPIRED state and recurring mandate will not be allowed. Mandatory only for UPI Mandate.

block_funds Boolean Set to TRUE if funds have to be blocked while a mandate is being created. Should be TRUE for ONETIME and FALSE for Recurring. By default, value will be TRUE for ONETIME and FALSE for Recurring.

rule_value

Integer

Determines the day of week or month that a mandate will be executed, depending on the mandate.frequency.

Description for rule.value

Possible values (Integer format):

1-7	when frequency is WEEKLY. In weekly, serial numbers start from Monday. Monday represents 1 and Sunday represents 7.
1-16	when frequency is FORTNIGHTLY. This mandate is executed twice a month. First day of the month is represented by value ‘1’ and ends with ‘15’ on 15th day of the month. Then again starts with ‘1’ for 16th of the month and ends with the last day of the month.
1-31	when frequency is MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, orYEARLY.

Check here for additional rules on this value.

rule_type String ON / BEFORE / AFTER
For Razorpay, rule_type will be updated to BEFORE.
For Paytm, rule_type will be updated to AFTER


revokable_by_customer	Boolean	If FALSE, the mandate cannot be revoked by the customer once set. Applicable only for UPI mandate. It should be TRUE for Recurring and TRUE/FALSE for ONETIME. By default, value will be TRUE
bank_details:wwwwnwww {param1, param2,...}	Object String	Bank details. (This object was also found in the "Card" response for the List Mandate API.)

Bank Details Object Parameters:

Field	Type	Description
bank_name	String	Name of bank
account_number	String	Bank account number
beneficiary_name	String	Name of the customer in a given bank account
ifsc	String	IFSC code for a bank branch


payment_links:wwwwwwwwii {web, mobile, iframe}	Object String	Three links for a Desktop , Mobile, and iFrame checkout screen for the given order (Parameters listed in table below - click to open)

Payment Links Object Parameters:

Field	Type	Description
web	String	Link to checkout page that is optimized for Desktop for the given order.
mobile	String	Link to Mobile optimized checkout page for the given order.
iframe	String	Link to iFrame checkout screen. This is typically embedded inside of your own page.

Payment Links
These links can directly be emailed or messaged to your customers. They will be redirected using a link to enter payment information. If you wish to use your own branding, then you can embed the iframe link into your page. Note that, these links are not valid perpetually. As soon as your order expires (this can be changed via our dashboard), the link will cease to work.


txn_detail:wwwwwnnwwwww {param1, param2, ....}	Object String	Object containing transaction details wwww

Transaction Detail Object Parameters:

Field	Type	Description	Example
txn_uuid	String	Transaction UUID (available in Order Status API response)	"eulneT9JkaAPa1uv"
txn_object_type	String	Transaction object type	"EMANDATE_REGISTER"
txn_id	String	Transaction ID	"11327833"
txn_amount	String	Amount of transaction	1
tax_amount	String	Amount of tax applied	null
surcharge_amount	String	Extra fee charged by merchant on payment	null
status	String	Status of the order (see Status Mapping table below.)	"CHARGED"
source_object_id	String	ID of source object	"91887"
source_object	String	Set to "MANDATE"	"MANDATE"
redirect	boolean	If true, the user is redirected to the `return_url` configured for the order.	false
order_id	String	Unique Identifier for the order.	"145678234"
net_amount	String	Net amount of order	1
gateway_id	String	Unique numeric identifier for your preferred gateway. (Refer to "Gateway Mapping" table.)	19
gateway	String	Name or your preferred gateway	"PAYTM_V2"
express_checkout	boolean	True if using Express Checkout	false
error_message	String	Bank error message	""
error_code	String	Numeric code of bank error message	""
currency	String	ISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: `INR`	"INR"
created	Date- Time	Date time (ISO representation) when order was created	"2020-04-28T06:31:37Z"


payment_gateway_response:i {param1, param2, ....}	Object String	Object containing payment gateway details (Parameters listed in table below - click to open)

Payment Gateway Response Object Parameters:

Field	Type	Description	Example
txn_id	String	Transaction ID	"11327833"
rrn	String	Authorization Retrieval Reference Number	"502913366745"
resp_message	String	Result of API action	"Payment Successful"
resp_code	String	Numeric code of response message	"0"
epg_txn_id	String	Electronic Payment Gateway transaction ID	"1532690566017"
created	Date- Time	Date time (ISO representation) when order was created	"2020-04-28T06:31:37Z"
auth_id_code	String	Authorization ID Code	"475926"


card:wwwwwwwwwwwwwwt {param1, param2, ....}	Object String	Object containing credit/debit card details

Card Object Parameters:

Field	Type	Description
using_token	Boolean	True if using a token
using_saved_card	Boolean	True if using a saved card
saved_to_locker	Boolean	True if card has been saved to locker
last_four_digits	String	Last four digits of card number
name_on_card	String	Card holder name. Should contain alphabetical characters only.
expiry_year	String	Expiry year of the card (Format: "yyyy")
expiry_month	String	Expiry month of the card (Format: "mm")
card_type	String	"CREDIT" or "DEBIT"
card_reference	String	Unique reference ID for card (if any)
card_issuer	String	Code for bank that issued the card (Example: "HDFC Bank")
card_isin	String	International Securities Identification Number for card (Example: "545721")
card_fingerprint	String	Card fingerprint
card_brand	String	Brand of card ("MASTERCARD", "VISA", etc.)


merchant_id	String	Unique identifier for the merchant.
order_id	String	Unique Identifier for the order. It is suggested to keep the `order id` length at a maximum of 21 characters irrespective of payment methods and gateways.
id	String	Unique ID generated by Juspay for the given order.
customer_id	String	Customer Identifier against which a mandate should be created. This has to be unique for a customer
customer_email	String	Email address of the customer. Must be present if backend gateway requires it.
customer_phone	String	Mobile number or fixed line number of the customer. Must be present if backend gateway requires it.
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. Fits well for impulse purchase usecases.
status	String	Status of the order. If you receive “NEW”, then the order is successfully created. See Appendix for status mapping.
status_id	Integer	Status ID is a numeric id corresponding to the status value. See Appendix for code meaning.
amount	Double	This is the amount that a customer will be charged in this transaction. Will accept double values with up to two decimal places. For example, 100.15 is valid input but 100.1532 is not valid.
effective_amount	Double	Amount that the customer actually pays
currency	String	ISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: `INR`
refunded	Boolean	Boolean value that determines if the amount was refunded or not.
amount_refunded	Double	Amount that has been refunded so far for this order.
date_created	Date- Time	Date-time of mandate order creation
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.
udf1	String	udf1 to udf10 - User defined field which will be echoed back in the response from Juspay with a Max character limit of 255.
udf2	String
udf3	String
udf4	String
udf5	String
udf6	String
udf7	String
udf8	String
udf9	String
udf10	String
txn_id	String	Transaction ID
txn_uuid	String	Transaction UUID
gateway_id	String	Unique numeric identifier for your preferred gateway. (Refer to "Gateway Mapping" table.)
gateway_reference_id	String	Alphabetic reference to the payment gateway used
bank_pg	String	Payment gateway for bank.
metadata: {param1, param2,...}	Object	Used for sending custom parameters to the payment aggregators, irrespective of default parameters. Check here for parameter list.
offers: [{...},{...},...]	Array of Objects	The mechanism of running offers is the responsibility of merchants in collaboration with PG/Banks.
bank_error_code	String	Bank Error Code
bank_error_message	String	Bank Error Message
payment_method_type	String	Must be either CARD, NB, WALLET, or UPI. Entered when creating the order or mandate
payment_method	String	Entered when creating the order or mandate. Found in the given tables for the corresponding API and transaction type.
payer_vpa	String	Payer VPA used during setting up mandate
auth_type	String	Type of authentication used

Another possible object that could be included in the response:


Refunds: [{...},{...},..] wwwwwwwwwwww	Array of Objects	An array of Refund Objects with details of each refund (returned with the Refund Order API). Should be returned if `refunded`is set to `true` in response.

Parameters for each object in the Refunds array:

Field	Type	Description
unique_request_id	String	The unique request ID that is passed during refund initiation. Do not pass any special characters.
status	String	The status of the refund initiated. Initial status will always be PENDING Status codes and meaning SUCCESS This means that the refund has been successfully executed. PENDING This would mean that the refund has been queued withJusPay or with the downstream system. FAILURE We were unable to process the refund successfully. You have to try again with a new `unique_request_id`. MANUAL_REVIEW This would mean that the refund request was sent an ambigious response from the payment gateway and the merchant has to manually reconcile it with the payment gateway to get the proper response. Also, any refunds which are in pending for more than 10 days are sent for manual review.
sent_to_gateway	Boolean	The flag denotes if the refund was initiated to gateway. The initial status is always false, as refunds are queued at Juspay for a maximum of 15 minutes.
refund_type	String	The type of refund. Values can be STANDARD or INSTANT
refund_source	String	The name of gateway
ref	String	The refund ID provided by the PG
initiated_by	String	The source of initiation
id	String	The reference ID provided by PG, if not available then its mapped to the unique request ID.
error_message	String	The error message provided by the PG
error_code	String	The error code provided by the PG
amount	Integer	The refund amount passed in the request
created	Time- stamp	The timestamp when refund was created

Payment Status Object

- Response for the Mandate Registration and Mandate Execution API.

Note:

This is the same as the Payment Status Object returned for Payments API requests (with three extra parameters: "txn_uuid, payment.sdk_params":{...}, and offer_details:{....}.

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:wwiw {{...},{...}}	Object	Contains `authentication` object: {`method, url, params`} (also `sdk_params` object for UPI Intent)

Parameters for the payment object:
{click to open)


authentication: {method, url, params}	Object		Authentication parametersww

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.


sdk_params: {{...},...}	Object	SDK parameterswwwwww (Used only for UPI Intent)

Parameters the sdk_params object:
(click to open)


scheme	String	Should be "mandate"
uri_params: {param1, param2,...}	Object	URI parameterswwwwtwww

Parameters for the uri_params object:
(click to open)

Parameter	Type	Example
validitystart	String	"eulcEPzPd244hfrGShFpH"
validityend	String	"24082037"
tr	String	"PAYTMSUBS202206203480824046791145"
tn	String	"Amount%20to%20be%20paid%20now%20is%20Rs%201.00"
tid	String	"PYTM20220620937257791803424"
recur	String	"ASPRESENTED"
purpose	String	"14"
pn	String	"test"
pa	String	"[email protected]"
orgid	String	"00000"
mode	String	"00"
mn	String	"Subscription%20for%20testaccount"
mc	String	"5811"
cu	String	"INR"
amrule	String	"MAX"
am	String	"1000.00"


offer_details:wi {`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

Notification Status Object

- Response for the Notification and Notification Status API.

Parameter	Type	Description
id	String	Unique identifier provided by Juspay. i.e. "1957069"
source_object	String	Source object for notification. i.e. “MANDATE”
source_object_id	String	Source object for notification. `mandate_id` in this case. i.e. "92025"
object	String	Must be set to `"notification"`
object_reference_id	String	Unique Identifier passed in the request. I.e. "1234578"
provider_name	String	Name of the provider. Gateway name in this case I.e. "PAYTM_V2"
notification_type	String	Type of notification. I.e. “SMS”
description	String	Reason for debit passed in the request
status	String	Status of Notification. Must be one of these four states: CREATED - Notification created in Juspay System, but not yet initiated to gateway PENDING - Initiated to the Payment Gateway, and awaiting the notification status from gateway SUCCESS - Success from gateway FAILURE - Failed from gateway
date_created	String	Date-time of notification created in UNIX EPOCH timestamp (UTC timezone) format. i.e. "1598960071"
last_updated	String	Date-time of notification updated in UNIX EPOCH timestamp (UTC timezone) format. i.e. "1598960071"
metadata	String	Metadata passed in the request

mandate: {mandate_id}	Object String	Mandate ID provided in the request: i.e. "4rKxSj3bNXs7RQcdtajAkb"
source_info: {param1, param2,...}	Object	JSON block of source info provided in the request.

Parameters for the source_info object:
(click to open)


amount	String	Amount passed in the request. i.e. "100.00"<
txn_date	String	`txn_date` passed in the request. Format: UNIX EPOCH timestamp (UTC timezone). i.e. "1634057114"
mandate.display_invoice_number	String	The display invoice number that was passed in the request. i.e. "INVN67Mzd6wMX4xPVBC"


provider_response: {param1, param2}	Object	JSON block of response from gateway.

Parameters for the provider_response object:
(click to open)


provider_ref_id	String	Reference Number provided by downstream gateway. i.e. "IN0DF815118772"
notification_date	String	Date on which notification was sent by downstream gateway. I.e. "1634057114" Specific to PAYTM_V2

An array of Mandate Objects, each of which includes a Payment Info Object:

- Response for the List Mandate API.

Parameter	Type	Description
object	String	"list"
list: [{...},{...},..]	Array	An array of Mandate Objects (see table below)
total	Int	Total mandates set against customer_id
offset	Int	Offset from start (default is 0)
count	Int	Count of mandate objects to be included in response Default is same as 'total'

Mandate Objects: The elements returned in the list array are Mandate Objects, each of which includes a Payment Info Object. This provides details of all mandates a customer has (or had) with a merchant.

Note:

Mandate Object includes two extra parameters in this instance: mandate_debit_token and description

Field	Type	Description
status	String	Current status of the mandate. Must be one of the states listed below. ENUM format: / CREATED / ACTIVE / PAUSED / REVOKED / FAILURE / EXPIRED /
payment_info:wwwwwi {param1, param2,...}	Object nStringn	This contains the payment instrument details entered when the mandate was created (Parameters listed in table below - click to open)

Payment Info Object Parameters:

Field	Type	Description
payment_method_type	String	Payment method type used when creating the mandate. Must be either CARD, NB, WALLET, or UPI.
payment_method	String	Payment method used when creating the mandate. Found in the given tables for the corresponding Payment API and transaction type.
auth-type	String	Type of authentication used. This parameter is returned only with the "Card" and "NB" response".
upi_details:wwwwwwi {payer_vpa}	Object String	UPI details related to customer. Currently just one parameter: `payer_vpa`

UPI Details Object Parameter:

Field	Type	Description
payer_vpa	String	Payer VPA used during setting up mandate.


card:wwwwwwwwwiww {param1, param2,...}	Object String	Card details. This parameter is included as shown in the "Card" response".

Card Object Parameters:

Field	Type	Description
using_saved_card	Boolean	True if using a saved card
saved_to_locker	Boolean	True if card has been saved to locker
last_four_digits	String	Last four digits of card number
name_on_card	String	Card holder name. Should contain alphabetical characters only.
expiry_year	String	Expiry year of the card (Format: "yyyy")
expiry_month	String	Expiry month of the card (Format: "mm")
card_type	String	"CREDIT" or "DEBIT"
card_issuer	String	Code for bank that issued the card (Example: "HDFC Bank")
card_isin	String	International Securities Identification Number for card (Example: "545721")
card_brand	String	Brand of card ("MASTERCARD", "VISA", etc.)


bank_details:wwwnwww {param1, param2,...}	Object String	This block will be available for only NB / CARD and `mandate_type` = EMANDATE mandate flows.

Bank Details Object Parameters:

Field	Type	Description
object	String	"bank_account"
id	String	Bank account ID generated by Juspay
customer_id	String	Customer ID sent in request. (Customer ID is provided by juspay or is the object reference ID given by merchant during customer creation.)
date_created	String	Date that account was created
bank_name	String	**Name of bank
account_number	String	Bank account number
beneficiary_name	String	Name of the customer in a given bank account
ifsc	String	IFSC code for a bank branch
validation_amount	String	Amount that account is validated for
currency	String	Type of currency
validation_status	String	Status of account (CREATED, PENDING, or ACTIVE)
last_validated	String	Time/date of most recent validation
metadata: {param1, param2, ....}	String	Custom key-value sets sent in previous request

NOTE:

Only those parameters in bold were shown in the response for this API.

mandate_id String Mandate ID is a unique identifier generated and sent by Juspay after mandate creation. Must be sent with the Mandate Execution, Notification, and Revoke Mandate APIs.

mandate_debit_token String One time token for recurring mandate execution. Allows a charge without a 2nd factor.

mandate_token String Mandate token is a unique identifier generated and sent by Juspay after mandate creation for one-time use. Allows a charge without a 2nd factor.

max_amountwwwwwi String Maximum amount of mandate set while creating a mandate. Mandatory only if mandate.amount_rule = VARIABLE.

currency String ISO string of the currency. Default value: INR (Indian Rupee). Among other accepted values are EUR, USD, GBP.

activated_at String Time stamp of mandate activation

start_date String Mandate start date in UNIX EPOCH timestamp (UTC timezone) format. In case of UPI mandate, the start date has to be today’s date. Mandatory only for UPI Mandate

end_date String Mandate end date in UNIX EPOCH timestamp (UTC timezone) format, when a mandate will move to EXPIRED state, and recurring mandate execution will not be allowed. Mandatory only for UPI Mandate.

amount_rule String Data type ENUM
Possible values: FIXED, VARIABLE.
By Default, it is considered as VARIABLE.
In case of FIXED, max amount will be equal to amount

mandate_type-- String EMANDATE in case of UPI/NB/Wallet payment
MANDATE in case of Card payment

block_fund Boolean Set to TRUE if funds have to be blocked while a mandate is being created. Should be TRUE for ONETIME and FALSE for Recurring. By default, value will be TRUE for ONETIME and FALSE for Recurring.

frequency

String

Defines the frequency of mandate execution, or how often a customer should be charged.

Description for mandate.frequency

Possible values (ENUM format):

ONETIME, DAILY, WEEKLY, FORTNIGHTLY, MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED

Default: ASPRESENTED

Check below for additional rules on this value.

rule_type String ON / BEFORE / AFTER
For Razorpay, rule_type will be updated to BEFORE.
For Paytm, rule_type will be updated to AFTER

rule_value

Integer

Determines the day of week or month that a mandate will be executed, depending on the mandate.frequency.

Description for rule.value

Possible values (Integer format):

1-7	when frequency is WEEKLY. In weekly, serial numbers start from Monday. Monday represents 1 and Sunday represents 7.
1-16	when frequency is FORTNIGHTLY. This mandate is executed twice a month. First day of the month is represented by value ‘1’ and ends with ‘15’ on 15th day of the month. Then again starts with ‘1’ for 16th of the month and ends with the last day of the month.
1-31	when frequency is MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, orYEARLY.

Check below for additional rules on this value.

description String Short description for the order such as product name, plan name.


revokable_by_customer	Boolean	If FALSE, the mandate cannot be revoked by the customer once set. Applicable only for UPI mandate. It should be TRUE for Recurring and TRUE/FALSE for ONETIME. By default, value will be TRUE

Mandate Status Mapping - Mandate status codes and meaning:

Status	Description
CREATED	Mandate has been created, but awaiting status from PG.
ACTIVE	When PG accepts the chosen mode of payment, the mandate is set to the active state. The state remains ACTIVE (except when PAUSED temporarily) until terminated (either when mandate expires or customer/merchant decides to revoke the mandate).
PAUSED	Customer has an option to pause the mandate. Status changes to PAUSED when customer exercises this option.
REVOKED	Mandate is revoked by either the customer or the merchant. Revoked is a terminal state, once Revoked, the status cannot be changed.
FAILURE	Mandate creation was unsuccessful. This is a terminal state, the merchant has to create a new mandate if failed.
EXPIRED	Mandate validity has expired. This is a terminal state.

Special considerations for certain values of the mandate.rule_value / mandate.frequency parameters: (click to view)

Calculating the day of mandate exectution for certain values of mandate.rule_value when mandate.frequency is set to 'FORTNIGHTLY' or 'MONTHLY'.

mandate.frequency = FORTNIGHTLY:

1. If the value is ‘14’, ‘15’, or ‘16’, and falls on the latter half of February (16th to 28th), then the mandate shall execute on the last day of February.

2. If the mandate start date is 24th January 2018 with value ‘16’, then the first

debit will be on 31st January, followed by 15th February, 28th February,

15th March, 31st March, and so on.

3. If the value is ‘16’, and the month has only 30 days, then the mandate should execute on 30th.

4. If the mandate start date is 29th January, and the value is ‘4’, then the first debit will be on 4th February, followed by 19th February, 4th March, and so on.

mandate.frequency = MONTHLY:

1. If the value is ‘29’, ‘30’, or ‘31’, and falls in February, then the mandate shall

execute on the last day of February.

2. If the value is ‘31’, and the next executable month has 30 days, then the

mandate will execute on the 30th.

3. If the mandate start date is 29th January and the value is ‘17’, then the first

debit will be on 17th February.

"mandate_id", "mandate_status"

- Response for the Revoke Mandate API.

Parameter	Type	Description
mandate_id	String	Unique identifier for the mandate sent by Juspay after mandate creation. `mandate_id` can be obtained from the List Mandate API response.
*mandate_status	String	Current status of the mandate. Must be one of the states listed in this table: (ENUM format) CREATED / ACTIVE / PAUSED / REVOKED / FAILURE / PENDING / EXPIRED