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

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 the 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. You can use this set of APIs to create a new customer or check the status of an existing customer.

Mandate Status - During the entire journey, a mandate once created can take up any of the following states:       (click to open table)
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.
PENDINGMandate is in a pending state.
EXPIREDMandate validity has expired. This is a terminal state.
Response Parameters for the Create Mandate Order API:  (click to view)
Note:
Response parameters are the same as for the Create Order API (Status, Redirect Info), except that the unique ID is generated for the mandate instead of order (mandate_id).
ParameterTypeDescription
mandate_idStringUnique ID generated by Juspay for the given mandate.
Identifier for the new mandate should be returned, not just "id".
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: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.

   APPENDIX   - Transaction 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
The request for the Create Mandate Order API consists of the following Parameter Groups and Objects:
(click to open tables)        Each parameter is also listed below:
Note:
Check table here for additional request parameters that may be required depending on the payment gateway or aggregator used on the backend.
(click to view & move left to right)
ParameterHDFCICICIAxisPayUCitrusPayTMEBSRazorPayCCAvenue
order_idYesYesYesYesYesYesYesYesYes
amountYesYesYesYesYesYesYesYesYes
customer_idYesYesYesYesYesYesYesYesYes
customer_emailYesYesYesYesYesYesYesYesYes
customer_phoneOptionalOptionalOptionalYesYesYesYesYesYes
descriptionOptionalOptionalYesYesYesYesYesYesYes
product_idNoNoNoNoNoNoNoNoNo
billing_address_first_nameNoNoNoOptionalOptionalNoYesNoYes
billing_address_last_nameNoNoNoOptionalOptionalNoYesNoYes
billing_address_line1NoNoNoOptionalOptionalNoYesNoYes
billing_address_line2NoNoNoOptionalOptionalNoYesNoYes
billing_address_line3NoNoNoOptionalOptionalNoYesNoYes
billing_address_cityNoNoNoOptionalOptionalNoYesNoYes
billing_address_stateNoNoNoOptionalOptionalNoYesNoYes
billing_address_countryNoNoNoOptionalOptionalNoYesNoYes
billing_address_postal_codeNoNoNoOptionalOptionalNoYesNoYes
billing_address_phoneNoNoNoOptionalOptionalNoYesNoYes
billing_address_country_code_isoNoNoNoOptionalOptionalNoYesNoYes
shipping_address_first_nameNoNoNoOptionalOptionalNoYesNoYes
shipping_address_last_nameNoNoNoOptionalOptionalNoYesNoYes
shipping_address_line1NoNoNoOptionalOptionalNoYesNoYes
shipping_address_line2NoNoNoOptionalOptionalNoYesNoYes
shipping_address_line3NoNoNoOptionalOptionalNoYesNoYes
shipping_address_cityNoNoNoOptionalOptionalNoYesNoYes
shipping_address_stateNoNoNoOptionalOptionalNoYesNoYes
shipping_address_countryNoNoNoOptionalOptionalNoYesNoYes
shipping_address_postal_codeNoNoNoOptionalOptionalNoYesNoYes
shipping_address_phoneNoNoNoOptionalOptionalNoYesNoYes
shipping_address_country_code_isoNoNoNoOptionalOptionalNoYesNoYes

    Parameter Groups:

   Order Info Parameters:
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.
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 Adress Parameters:
FieldTypeDescription
billing_address_first_nameStringFirst name in the billing address
billing_address_last_nameStringLast name in the billing address
billing_address_line1StringLine1 in the billing address
billing_address_line2StringLine2 in the billing address
billing_address_line3StringLine3 in the billing address
billing_address_cityStringBilling address city
billing_address_stateStringBilling address state
billing_address_countryStringBilling address country
billing_address_postal_codeStringBilling address postal code or zip code
billing_address_phoneStringMobile or phone number in the billing address
billing_address_country_code_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:
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

   Objects:

   Mandate Object Parameters:
FieldTypeDescription
max_amount*StringMaximum amount for a mandate. Mandatory only if mandate.amount_rule = VARIABLE.
frequencyStringDefines the frequency of mandate execution, or how often a customer should be charged.
(see description for mandate.frequency below.)
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.
rule_valueStringDetermines the day of week or month that a mandate will be executed, depending on the mandate.frequency.
(see description for mandate.rule_value below.)
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:
FieldTypeDescription
bank_account_numberStringBank account number of VPA used. Used only if downstream supports third party validation.
bank_ifscStringIFSC code for a given bank.
PAYTM_V2: SUBSCRIPTION_GRACE_DAYSStringNumber 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_COUNTStringApplicable only for Paytm. By default 2 for UPI mandate.
PAYTM_V2: GATEWAY_REFERENCE_IDStringCustomized PAYTM_V2 parameter for the payment aggregators. This was found in request, but not in parameter list.

   Options Object Parameter:
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
Other Parameters sent by API, but not included in an Object or Parameter Group:
HEADER:
FieldTypeDescription
x-merchantid-----*StringMerchant ID which would have been issued while registering with Juspay

    * = Required

  mandate.frequency / mandate.rule_value definitions:     (click to view)
mandate.frequency
Description: Defines the frequency of mandate execution, or how often a customer should be charged.
Data type:    String (ENUM format)
Possible values:
ONETIME, DAILY, WEEKLY, FORTNIGHTLY, MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
Default:        ASPRESENTED

mandate.rule_value
Description: This value determines the day of week or month that a mandate will be executed, depending on the mandate.frequency.
Data type:    String (Integer format)
Possible values:
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.
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.

Language
Authentication
Basic
base64
:
Click Try It! to start a request and see the response here!