Body
Create Order
This is the same API used for creating order for one-time payments. It can also be used to create a mandate for your existing customers with subscription specific details like amount, subscription frequency, duration of the mandate, Required/Optional mandate flow, etc. Use the order 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 Customer APIs to create a new customer or check the status of an existing customer.
The API is not required for the merchants using Juspay's Payment Page product.
During the entire journey, a mandate once created can take up any of the following states:
Scroll inside to view more
|
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. This is a terminal state until mandate expires or customer/merchant wants 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.
|
2 columns 7 rows
Note
Values that mandate.rule_value can adopt depending on mandate.frequency
Fortnightly
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.
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.
If the value is ‘16’ and the month has only 30 days then the mandate should execute on 30th.
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.
Monthly
If the value is ‘29’, ‘30’ or ‘31’ and falls on February then the mandate shall execute on the last day of February.
If the value is ‘31’ and the next executable month has 30 days only then the mandate will execute on 30th
If the mandate start date is 29th January and the value is ‘17’ then the first debit will be on 17th February
Request
Response
API Endpoints
Sandbox Link
POST
https://sandbox.juspay.in/orders
Production Link
POST
https://api.juspay.in/orders
Headers
x-merchantid
*
String
Mandatory
Merchant ID which would have been issues while registering with Juspay
Content-Type
String
It should be application/x-www-form-urlencoded
x-routing-id
*
String
Required
We recommend passing the customer_id as the x-routing-id. If the customer is checking out as a guest, you can pass an alternative ID that helps track the payment session lifecycle. For example, this could be an Order ID or Cart ID.
Warning
This ID is associated with the customer. It plays a key role in ensuring consistency and maintaining connections across different systems. If you fail to pass the same x-routing-id for the same customer in all related API calls, it could lead to issues with API functionality. Therefore, it’s crucial that you use the same x-routing-id for all requests tied to the same customer.
Example:- customer_1122
Request Schema: application/json
Request Parameters
order_id
*
String
Mandatory
Unique Identifier for the order. You can pass your native order ID here.
amount
*
doube
Mandatory
This is the amount that a customer will be charged in this transaction.
currency
String
ISO string of the currency. Default value: INR
customer_id
*
String
Mandatory
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.
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
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.
billing_address_first_name
String
First name in the billing address
billing_address_last_name
String
Last name in the billing address
billing_address_line1
String
Line 1 in the billing address
billing_address_line2
String
Line 2 in the billing address
billing_address_line3
String
Line 3 in the billing address
billing_address_city
String
Billing address city
billing_address_state
String
Billing address state
billing_address_country
String
Billing address country
billing_address_postal_code
String
Billing address postal code or zip code
billing_address_phone
String
Mobile or phone number in the billing address
billing_address_country_code_iso
String
ISO Country code Default value: IND
shipping_address_first_name
String
First name in the shipping address
shipping_address_last_name
String
Last name in the shipping address
shipping_address_line1
String
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
options.create_mandate
*
String
Mandatory
For merchants who wants 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”
mandate object
Object
max_amount
*
String
Mandatory
Maximum amount for a mandate. Required, only when amount type is variable. If amount type is fixed, amount is considered as max amount.
frequency
String
Defines the frequency of mandate execution, how often a customer should be charged.
Data type ENUM:
ONETIME (Supported only by UPI)
DAILY
WEEKLY
FORTNIGHTLY
MONTHLY
BIMONTHLY
QUARTERLY
HALFYEARLY
YEARLY
ASPRESENTED
By Default it is considered as ASPRESENTED
If frequency is selected anything other than ONETIME, DAILY, ASPRESENTED, rule_value should be passed mandatorily.
Note:
1. Daily is not supported by Billdesk and Paytm (For cards)
2. In UPI AutoPay, ONETIME frequency, Mandate is valid only for 90 Days
amount_rule
String
Data type ENUM: FIXED, VARIABLE. By default, it is considered as VARIABLE. In case of FIXED amount_rule.
end_date
String
Mandatory for UPI Mandate. Mandate end date in UNIX EPOCH timestamp (UTC timezone). Post end date, mandate will move to EXPIRED state and recurring mandate will not be allowed.By default value will be Mandate start date + 30 years
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
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
String
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, or YEARLY.
Not required when frequency is ONETIME, DAILY, 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.
Refer notes for detailed explanation.
rule_type
String
ON| BEFORE| AFTER
For Razorpay, rule_type will be updated to BEFORE. For Paytm, Billdesk rule_type will be updated to AFTER.
recurring_amount
String
Recommended
Recurring amount for a mandate.
For variable amount type, Recurring amount should not be greater than max_amount.
For fixed amount type, Recurring amount should not be greater than order amount.
Recommended, if update mandate flow is used later.
udf1-10
String
metadata object
object
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.
bank_account_details
String
Applicable for TPV Mandate. This is a array of JSON objects and each JSON object includes set of parameters as below 1. bank_account_number 2. bank_ifsc 3. juspay_bank_code 4. bank_beneficiary_name 5. bank_account_type 6. bank_account_id If a merchant uses juspay bank_account feature APIs, then sending bank_account_id is sufficient.
auto_refund_post_success
String
Pass the param if you want to refund the debit amount while setting up the mandate, this will keep you mandate in active state and initiate a refund call to the PG
Example:- True
order_type
String
TPV_PAYMENT. Applicable only for TPV Mandates.
200 : Success
Response Body
200 : UPI
Object
status_id
integer
status
String
payment_links
object
web
String
mobile
String
iframe
String
order_id
String
id
String
200 : Card
object
status
String
status_id
integer
id
String
order_id
String
payment_links
object
web
String
mobile
String
iframe
String
200 : Netbanking
object
status
String
status_id
Integer
id
String
order_id
String
payment_links
object
web
String
mobile
String
iframe
String