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

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.
FieldTypeDescription
max_amount*StringMaximum amount for a mandate. Mandatory only if mandate.amount_rule = VARIABLE.
amount_ruleStringData 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*StringMandate 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*StringMandate 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_fundsBooleanSet 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.
frequencyStringDefines 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_valueStringDetermines 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-7when frequency is WEEKLY. In weekly, serial numbers start from Monday. Monday represents 1 and Sunday represents 7.
1-16when 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-31when 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_typeStringON / BEFORE / AFTER
For Razorpay, rule_type will be updated to BEFORE.
For Paytm, rule_type will be updated to AFTER
revokable_by_customerBooleanIf 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.
FieldTypeDescription
bank_account_numberwStringBank account number of VPA used. Used only if downstream supports third party validation.
bank_ifscStringIFSC code for a given bank.
PAYTM_V2:
SUBSCRIPTION_GRACE_DAYS
StringNumber 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
StringApplicable only for Paytm. By default 2 for UPI mandate.
PAYTM_V2:
GATEWAY_REFERENCE_ID
StringCustomized 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.
FieldTypeDescription
create_mandate*StringMerchants 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.
FieldTypeDescription
amount*StringAmount for which notification is to be sent to customer
I.e. "100.00"
txn_date*StringDate 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.
FieldTypeDescription
order_id*StringUnique Identifier for the order. You can pass your native order ID here.
amount*StringAmount 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_typeStringSet to “TPV_PAYMENT” if using Third-Party Validation.
currency*StringISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: INR
customer_id*StringUnique ID for a customer that you get after running the Create Customer API (Check Customer section for more details)
customer_email*StringEmail 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. Fits well for impulse purchase usecases.
gateway_idStringSpecify 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.
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_iso---StringISO 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:
- 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.
FieldTypeDescription
udf1StringUser Defined Field
udf2String
udf3String
udf4String
udf5String
udf6String
udf7String
udf8String
udf9String
udf10String
  Payment Method Parameters:
- Used only for the Mandate Registration API.
Note:
These are the same Payment Method Parameters used in the Payments API requests.
FieldTypeDescription
order_id*StringUnique Identifier for the order.
merchant_id*StringID of the merchant_account that you hold with us.
payment_method_type*StringPayment 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*StringPayment 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*BooleanWe 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*StringIf 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.
FieldTypeDescription
bank_nameStringName of bank that is holding the account
bank_account_number*StringBank account number. Required for emandate/e-NACH, or when mandate_type= EMANDATE.
bank_beneficiary_nameStringAccount holder name. Should contain alphabetical characters only. Required for emandate/e-NACH, or when mandate_type= EMANDATE.
bank_ifscStringBank 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.
FieldTypeDescription
card_token*stringA 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_numberStringA valid credit/debit card number. Required when mandate_type= MANDATE for a new card transaction.
card_exp_yearStringRepresent the expiry year of the card as YY (two digits only). Required when mandate_type= MANDATE for a new card transaction.
card_exp_monthStringRepresent the expiry month of the card as MM (two digits only). Required when mandate_type= MANDATE for a new card transaction.
card_security_codeStringCVV of the card. Usually three digits. Required when mandate_type= MANDATE for a new card transaction.
name_on_cardStringCard holder name. Should contain alphabetical characters only. Required when mandate_type= MANDATE for a new card transaction.
save_to_lockerStringThis 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:
ParameterTypeDescription
upi_vpa*StringVPA to which the collect request must be sent
mandate type*StringEMANDATE in case of UPI/NB/Wallet.
MANDATE in case of card.
should_create_mandateBooleanThis 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:
ParameterTypeDescription
command*StringSet to “pre_debit_notify” for sending notification before execute mandate.
object_reference_id*StringMerchants unique Identifier for the request.
description*StringReason for debit that will be sent to user.
Max Length: 50
metadataStringFor 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:
ParameterTypeDescription
mandate_id*StringMandate ID sent by Juspay after mandate creation.
merchant_id*StringThe username you hold at Juspay
format*StringThe format of the response. Should be passed as json.
mandate.notification_idObject
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_numberObject
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_dateObject
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:
ParameterTypeDescription
command*StringTo be set as "revoke" to revoke an existing mandate
  Other request parameters for the Pause Mandate API:
ParameterTypeDescription
command*StringTo be set as "pause", to pause an active mandate
pause_start_dateStringDate in UNIX EPOCH timestamp (UTC timezone) format, when the mandate will be paused. Default value can be the current date.
pause_end_dateStringDate 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:
ParameterTypeDescription
command*StringTo be set as "resume" to resume a paused mandate
resume_dateString[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).
ParameterTypeDescription
idStringUnique ID generated by Juspay for the given order.
order_idStringGiven order ID.
statusStringStatus 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_idIntegerStatus 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:
FieldTypeDescription
webStringLink to checkout page that is optimized for Desktop for the given order.
mobileStringLink to Mobile optimized checkout page for the given order.
iframeStringLink 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
StatusIDMeaning
NEW10Newly created mandate
PENDING_VBV23Authentication is in progress. The customer has to approve the mandate through the PSP App of their choice.
CHARGED21Successful transaction. The subscription cost of the period has been charged.
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
  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:
ParameterTypeDescription
mandate:wwwwwwwwwwwn
      {param1, param2, ....}
Object
String
Object containing mandate details.
(Parameters listed in table below - click to open)
  Mandate Object Parameters:
FieldTypeDescription
mandate_idStringMandate 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_tokenStringMandate 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_statusStringCurrent status of the mandate. Must be one of the states listed in this table:
(ENUM format)  CREATED / ACTIVE / PAUSED / REVOKED / FAILURE / PENDING / EXPIRED
mandate_typeStringEMANDATE in case of UPI/NB/Wallet payment
MANDATE in case of Card payment
max_amountStringMaximum amount for a mandate. Mandatory only if mandate.amount_rule = VARIABLE.
currencyStringISO string of the currency. Default value: INR (Indian Rupee). Among other accepted values are EUR, USD, GBP.
activated_atStringTime stamp of mandate activation
This should be included also.
frequencyStringDefines 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_ruleStringData 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_dateStringMandate 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_dateStringMandate 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_fundsBooleanSet 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_valueIntegerDetermines 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-7when frequency is WEEKLY. In weekly, serial numbers start from Monday. Monday represents 1 and Sunday represents 7.
1-16when 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-31when 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_typeStringON / BEFORE / AFTER
For Razorpay, rule_type will be updated to BEFORE.
For Paytm, rule_type will be updated to AFTER
revokable_by_customerBooleanIf 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:
FieldTypeDescription
bank_nameStringName of bank
account_numberStringBank account number
beneficiary_nameStringName of the customer in a given bank account
ifscStringIFSC 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:
FieldTypeDescription
webStringLink to checkout page that is optimized for Desktop for the given order.
mobileStringLink to Mobile optimized checkout page for the given order.
iframeStringLink 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:
FieldTypeDescriptionExample
txn_uuidStringTransaction UUID (available in Order Status API response)"eulneT9JkaAPa1uv"
txn_object_typeStringTransaction object type"EMANDATE_REGISTER"
txn_idStringTransaction ID"11327833"
txn_amountStringAmount of transaction1
tax_amountStringAmount of tax appliednull
surcharge_amountStringExtra fee charged by merchant on paymentnull
statusStringStatus of the order (see Status Mapping table below.)"CHARGED"
source_object_idStringID of source object"91887"
source_objectStringSet to "MANDATE""MANDATE"
redirectbooleanIf true, the user is redirected to the return_url configured for the order.false
order_idStringUnique Identifier for the order."145678234"
net_amountStringNet amount of order1
gateway_idStringUnique numeric identifier for your preferred gateway. (Refer to "Gateway Mapping" table.)19
gatewayStringName or your preferred gateway"PAYTM_V2"
express_checkoutbooleanTrue if using Express Checkoutfalse
error_messageStringBank error message""
error_codeStringNumeric code of bank error message""
currencyStringISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: INR"INR"
createdDate-
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:
FieldTypeDescriptionExample
txn_idStringTransaction ID"11327833"
rrnStringAuthorization Retrieval Reference Number"502913366745"
resp_messageStringResult of API action"Payment Successful"
resp_codeStringNumeric code of response message"0"
epg_txn_idStringElectronic Payment Gateway transaction ID"1532690566017"
createdDate-
Time
Date time (ISO representation) when order was created"2020-04-28T06:31:37Z"
auth_id_codeStringAuthorization ID Code"475926"
card:wwwwwwwwwwwwwwt
      {param1, param2, ....}
Object
String
Object containing credit/debit card details
    Card Object Parameters:
FieldTypeDescription
using_tokenBooleanTrue if using a token
using_saved_cardBooleanTrue if using a saved card
saved_to_lockerBooleanTrue if card has been saved to locker
last_four_digitsStringLast four digits of card number
name_on_cardStringCard holder name. Should contain alphabetical characters only.
expiry_yearStringExpiry year of the card (Format: "yyyy")
expiry_monthStringExpiry month of the card (Format: "mm")
card_typeString"CREDIT" or "DEBIT"
card_referenceStringUnique reference ID for card (if any)
card_issuerStringCode for bank that issued the card
(Example: "HDFC Bank")
card_isinStringInternational Securities Identification Number for card    (Example: "545721")
card_fingerprintStringCard fingerprint
card_brandStringBrand of card ("MASTERCARD", "VISA", etc.)
merchant_idStringUnique identifier for the merchant.
order_idStringUnique 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.
idStringUnique ID generated by Juspay for the given order.
customer_idStringCustomer Identifier against which a mandate should be created. This has to be unique for a customer
customer_emailStringEmail address of the customer. Must be present if backend gateway requires it.
customer_phoneStringMobile number or fixed line number of the customer. Must be present if backend gateway requires it.
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. Fits well for impulse purchase usecases.
statusStringStatus of the order. If you receive “NEW”, then the order is successfully created. See Appendix for status mapping.
status_idIntegerStatus ID is a numeric id corresponding to the status value. See Appendix for code meaning.
amountDoubleThis 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_amountDoubleAmount that the customer actually pays
currencyStringISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: INR
refundedBooleanBoolean value that determines if the amount was refunded or not.
amount_refundedDoubleAmount that has been refunded so far for this order.
date_createdDate-
Time
Date-time of mandate order creation
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.
udf1Stringudf1 to udf10 - User defined field which will be echoed back in the response from Juspay with a Max character limit of 255.
udf2String
udf3String
udf4String
udf5String
udf6String
udf7String
udf8String
udf9String
udf10String
txn_idStringTransaction ID
txn_uuidStringTransaction UUID
gateway_idStringUnique numeric identifier for your preferred gateway. (Refer to "Gateway Mapping" table.)
gateway_reference_idStringAlphabetic reference to the payment gateway used
bank_pgStringPayment gateway for bank.
metadata:
  {param1, param2,...}
ObjectUsed 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_codeStringBank Error Code
bank_error_messageStringBank Error Message
payment_method_typeStringMust be either CARD, NB, WALLET, or UPI. Entered when creating the order or mandate
payment_methodStringEntered when creating the order or mandate. Found in the given tables for the corresponding API and transaction type.
payer_vpaStringPayer VPA used during setting up mandate
auth_typeStringType 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 refundedis set to true in response.
  Parameters for each object in the Refunds array:
FieldTypeDescription
unique_request_idStringThe unique request ID that is passed during refund initiation. Do not pass any special characters.
statusStringThe 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_gatewayBooleanThe 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_typeStringThe type of refund. Values can be STANDARD or INSTANT
refund_sourceStringThe name of gateway
refStringThe refund ID provided by the PG
initiated_byStringThe source of initiation
idStringThe reference ID provided by PG, if not available then its mapped to the unique request ID.
error_messageStringThe error message provided by the PG
error_codeStringThe error code provided by the PG
amountIntegerThe refund amount passed in the request
createdTime-
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.
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:wwiw
    {{...},{...}}
ObjectContains authentication object:
{method, url, params}
(also sdk_params object for UPI Intent)
 Parameters for the payment object:
     {click to open)
authentication:
    {method, url, params}
ObjectAuthentication parametersww
  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.
sdk_params: {{...},...}ObjectSDK parameterswwwwww
(Used only for UPI Intent)
  Parameters the sdk_params object:
      (click to open)
schemeStringShould be "mandate"
uri_params:
    {param1, param2,...}
ObjectURI parameterswwwwtwww
  Parameters for the uri_params object:
      (click to open)
ParameterTypeExample
validitystartString"eulcEPzPd244hfrGShFpH"
validityendString"24082037"
trString"PAYTMSUBS202206203480824046791145"
tnString"Amount%20to%20be%20paid%20now%20is%20Rs%201.00"
tidString"PYTM20220620937257791803424"
recurString"ASPRESENTED"
purposeString"14"
pnString"test"
paString"[email protected]"
orgidString"00000"
modeString"00"
mnString"Subscription%20for%20testaccount"
mcString"5811"
cuString"INR"
amruleString"MAX"
amString"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:
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
  Notification Status Object
- Response for the Notification and Notification Status API.
ParameterTypeDescription
idStringUnique identifier provided by Juspay.
i.e. "1957069"
source_objectStringSource object for notification.
i.e. “MANDATE”
source_object_idStringSource object for notification. mandate_id in this case.
i.e. "92025"
objectStringMust be set to "notification"
object_reference_idStringUnique Identifier passed in the request.
I.e. "1234578"
provider_nameStringName of the provider. Gateway name in this case
I.e. "PAYTM_V2"
notification_typeStringType of notification.
I.e. “SMS”
descriptionStringReason for debit passed in the request
statusStringStatus 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_createdStringDate-time of notification created in UNIX EPOCH timestamp (UTC timezone) format.
i.e. "1598960071"
last_updatedStringDate-time of notification updated in UNIX EPOCH timestamp (UTC timezone) format.
i.e. "1598960071"
metadataStringMetadata passed in the request
mandate:
     {mandate_id}
Object
String
 Mandate ID provided in the request:
 i.e. "4rKxSj3bNXs7RQcdtajAkb"
source_info:
    {param1, param2,...}
ObjectJSON block of source info provided in the request.
  Parameters for the source_info object:
      (click to open)
amountStringAmount passed in the request.
i.e. "100.00"<
txn_dateStringtxn_date passed in the request.
Format: UNIX EPOCH timestamp (UTC timezone).
i.e. "1634057114"
mandate.display_invoice_numberStringThe display invoice number that was passed in the request.
i.e. "INVN67Mzd6wMX4xPVBC"
provider_response:
    {param1, param2}
ObjectJSON block of response from gateway.
  Parameters for the provider_response object:
      (click to open)
provider_ref_idStringReference Number provided by downstream gateway.
i.e. "IN0DF815118772"
notification_dateStringDate 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.
ParameterTypeDescription
objectString"list"
list: [{...},{...},..]ArrayAn array of Mandate Objects     (see table below)
totalIntTotal mandates set against customer_id
offsetIntOffset from start (default is 0)
countIntCount 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
FieldTypeDescription
statusStringCurrent 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:
FieldTypeDescription
payment_method_typeStringPayment method type used when creating the mandate. Must be either CARD, NB, WALLET, or UPI.
payment_methodStringPayment method used when creating the mandate. Found in the given tables for the corresponding Payment API and transaction type.
auth-typeStringType 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:
FieldTypeDescription
payer_vpaStringPayer 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:
FieldTypeDescription
using_saved_cardBooleanTrue if using a saved card
saved_to_lockerBooleanTrue if card has been saved to locker
last_four_digitsStringLast four digits of card number
name_on_cardStringCard holder name. Should contain alphabetical characters only.
expiry_yearStringExpiry year of the card (Format: "yyyy")
expiry_monthStringExpiry month of the card (Format: "mm")
card_typeString"CREDIT" or "DEBIT"
card_issuerStringCode for bank that issued the card
(Example: "HDFC Bank")
card_isinStringInternational Securities Identification Number for card    (Example: "545721")
card_brandStringBrand 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:
FieldTypeDescription
objectString"bank_account"
idStringBank account ID generated by Juspay
customer_idStringCustomer ID sent in request. (Customer ID is provided by juspay or is the object reference ID given by merchant during customer creation.)
date_createdStringDate that account was created
bank_nameString**Name of bank
account_numberStringBank account number
beneficiary_nameStringName of the customer in a given bank account
ifscStringIFSC code for a bank branch
validation_amountStringAmount that account is validated for
currencyStringType of currency
validation_statusStringStatus of account (CREATED, PENDING, or ACTIVE)
last_validatedStringTime/date of most recent validation
metadata:
   {param1, param2, ....}
StringCustom key-value sets sent in previous request
NOTE:
Only those parameters in bold were shown in the response for this API.
mandate_idStringMandate 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_tokenStringOne time token for recurring mandate execution. Allows a charge without a 2nd factor.
mandate_tokenStringMandate 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_amountwwwwwiStringMaximum amount of mandate set while creating a mandate. Mandatory only if mandate.amount_rule = VARIABLE.
currencyStringISO string of the currency. Default value: INR (Indian Rupee). Among other accepted values are EUR, USD, GBP.
activated_atStringTime stamp of mandate activation
start_dateStringMandate 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_dateStringMandate 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_ruleStringData 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--StringEMANDATE in case of UPI/NB/Wallet payment
MANDATE in case of Card payment
block_fundBooleanSet 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.
frequencyStringDefines 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_typeStringON / BEFORE / AFTER
For Razorpay, rule_type will be updated to BEFORE.
For Paytm, rule_type will be updated to AFTER
rule_valueIntegerDetermines 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-7when frequency is WEEKLY. In weekly, serial numbers start from Monday. Monday represents 1 and Sunday represents 7.
1-16when 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-31when 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 below for additional rules on this value.
descriptionStringShort description for the order such as product name, plan name.
revokable_by_customerBooleanIf 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:
StatusDescription
CREATEDMandate has been created, but awaiting status from PG.
ACTIVEWhen 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).
PAUSEDCustomer has an option to pause the mandate. Status changes to PAUSED when customer exercises this option.
REVOKEDMandate is revoked by either the customer or the merchant. Revoked is a terminal state, once Revoked, the status cannot be changed.
FAILUREMandate creation was unsuccessful. This is a terminal state, the merchant has to create a new mandate if failed.
EXPIREDMandate 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.
ParameterTypeDescription
mandate_idStringUnique identifier for the mandate sent by Juspay after mandate creation. mandate_id can be obtained from the List Mandate API response.
*mandate_statusStringCurrent status of the mandate. Must be one of the states listed in this table:
(ENUM format)  CREATED / ACTIVE / PAUSED / REVOKED / FAILURE / PENDING / EXPIRED