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

Create Order with Payments

This API supports parameters from both the Create Order API and the Payments API.

To include Create Order API parameters, prefix them with order.
- Example: order.metadata.JUSPAY:gateway_reference_id
Parameters from the Payments API can be used directly as defined

If you are a PCI-compliant merchant, you can combine the Create Order API and the Payments API into a single API request.

Refer to the sample request and response below for implementation details.

Request

Response

API Endpoints

Sandbox Link

POST

https://sandbox.juspay.in/txns

Production Link

POST

https://api.juspay.in/txns

                      Basic Auth
                      *
                      

Base64 Encoded Username:Password

Required

Consists of two parts.

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

Example:- Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==

                      x-merchantid 
                      *
                      

String

Required

Merchant ID provided by Juspay

Example:-
merchant-id

                      Content-Type
                      
                      

String

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.

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

Body

Request Schema: application/json

                      order.order_id
                      *
                      

String

Required

Unique Identifier for the order. Should be Alphanumeric with character length less than 21.

Example:-
order-id-9876580

                      order.amount
                      *
                      

Double

Required

Amount that the customer has to pay. Will accept stringified double or integer values with upto two decimal places. For example, "100.15" and "100" are valid input but "100.1532" is not valid.

                      order.customer_id
                      
                      

String

It is the ID with which merchant refers to a customer object. This id is used to access the stored payment methods, allow EMI transactions and setup subscriptions.
In case of guest login it should be an empty string.

Example:-
customer-id-007

                      order.customer_email
                      
                      

String

Email address of the customer. If the backend gateway requires it, then you must send this value.

Example:-
test@gmail.com

                      order.customer_phone
                      
                      

String

Mobile number or fixed line number of the customer. If the backend gateway requires it, then you must send this value.

Example:-

9999999912

                      order.currency
                      
                      

String

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

                      order.return_url
                      
                      

String

A fully qualified URL which the customer will be redirected after payment completion. It is also required to provide the control back to SDK after the completion of transaction. This URL shouldn't contain any query parameters or Ip address. This URL takes higher precedence over the common return URL configured in your account settings.

Example:-
https://shop.merchant.com

                      merchant_id
                      *
                      

String

Required

ID of the merchant_account that you hold with us.

                      payment_method_type
                      *
                      

String

Required

Depending on type of payment to be processed.

Example:- CARD, NB, UPI

                      payment_method
                      
                      

String

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.

                      card_token
                      *
                      

String

Required

A valid card token obtained using /card/list API. If you send this parameter, then card_number, name_on_card, card_exp_year, 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.

                      card_number
                      *
                      

String

Required

A valid credit/debit card number

                      name_on_card
                      
                      

String

Card holder name. Should contain alphabetical characters only.

                      card_exp_year
                      *
                      

String

Required

Represent the expiry year of the card as YY (two digits only)

                      card_exp_month
                      *
                      

String

Required

Represent the expiry month of the card as MM (two digits only)

                      card_security_code
                      *
                      

String

Required

CVV of the card. Usually three digits. Optional for all VISA saved cards, SODEXO saved cards, and saved cards of select issuing banks of MASTERCARD

                      save_to_locker
                      *
                      

Boolean

Required

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. Only applicable for international cards.

                      tokenize
                      *
                      

Boolean

Required

This is a boolean variable and accepts true/false. If set to true, then the card will be tokenised when the transaction is successful. Only applicable for domestic cards

                      redirect_after_payment
                      *
                      

Boolean

Required

This is a boolean variable and accepts true/false. 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

Required

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.

                      order.metadata.auto_refund_post_success
                      *
                      

String

Required

Set it to true if you want to auto initiate refunds once the transaction is successful. For example, if you are doing refundable penny drop transactions for authentication/tokenization

                      sdk_params
                      *
                      

String

Required

This is default parameter required.

                      upi_app
                      *
                      

String

Required

Package name of the UPI app used by customer to make a payment

                      upi_vpa
                      *
                      

String

Required

Virtual Payment Address of the customer. Required for UPI Collect and TPV Collect.

                      txn_type
                      *
                      

String

Required

Type of UPI transaction (e.g., UPI_COLLECT, UPI_PAY). Needed in UPI Collect and Intent Mandate flows.

                      should_create_mandate
                      *
                      

Boolean

Required

Set to "true" to create mandate during transaction.

                      mandate_type
                      *
                      

String

Required

Type of mandate (e.g., EMANDATE). Required when registering mandates.

Example:- EMANDATE

                      order.options.create_mandate
                      *
                      

String

Required

REQUIRED / OPTIONAL. Indicates if mandate creation must be enforced.

                      order.mandate.max_amount
                      *
                      

String

Required

Maximum allowable debit under mandate.

                      order.mandate.amount_rule
                      
                      

String

Optional

FIXED or VARIABLE defines how the amount is treated under the mandate.

                      order.mandate.frequency
                      
                      

String

Optional

Frequency of mandate debit (e.g., MONTHLY, ASPRESENTED).

Example:- MONTHLY, ASPRESENTED

                      order.mandate.start_date
                      
                      

Timestamp

Optional

Timestamp when mandate becomes active.

                      order.mandate.end_date
                      
                      

Timestamp

Optional

Timestamp when mandate ends.

                      order.mandate.rule_value
                      
                      

String

Optional

Value representing execution interval based on frequency:

WEEKLY: 1 to 7
- Where 1 represents Monday and 7 represents Sunday
FORTNIGHTLY: 1 to 16
- First half of the month: Execution days range from 1 to 15.
- Second half of the month: Starting from the 16th, execution days range from 1 to the end of the month.
MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY: 1 to 31
Not required for ONETIME, DAILY, or ASPRESENTED
Gateway-specific behavior:
- Razorpay: rule_value considered is the last day of the week/month/year
- Paytm: rule_value considered is today’s date/day

                      order.mandate.rule_type
                      
                      

String

Optional

Rule to trigger recurring debit (ON, BEFORE, AFTER).

                      order.mandate.revokable_by_customer
                      
                      

Boolean

Optional

If true, mandate can be revoked by the customer.

                      order.mandate.block_funds
                      
                      

Boolean

Optional

If true, blocks funds during mandate creation.

                      order.metadata.JUSPAY:gateway_reference_id
                      
                      

String

Optional

Juspay's internal gateway reference.

                      order.metadata.bank_account_details
                      
                      

Array

Conditional

Required for TPV flows. Contains account no, IFSC, Juspay bank code.

                      order.order_type
                      
                      

String

Optional

Set to TPV_PAYMENT to enable TPV validation.

                      is_emi
                      
                      

Boolean

Default is false. Set it to true if the user wishes to perform an EMI transaction on the given card.

                      emi_bank
                      
                      

String

Represents the bank that issued the cardless EMI. Value must be one of the entries mentioned under EMI Bank in the support matrix below.
Bank code can be referred here.

                      emi_tenure
                      
                      

Integer

The tenure of the EMI in number of months.

                      emi_type
                      
                      

String

The type of EMI ie STANDARD_EMI

Response Body

                      order_id
                      
                      

String

:order_id

                      txn_id
                      *
                      

String

Mandatory

                      status
                      
                      

String

PENDING_VBV

                      payment
                      
                      

Object

                      authentication.method
                      
                      

String

                      authentication.url
                      
                      

String

                      sdk_params
                      
                      

object

tr

String

tid

String

                      merchant_vpa
                      
                      

String

                      merchant_name
                      
                      

String

mcc

String

                      amount
                      
                      

String

                      txn_uuid
                      
                      

String

:txn_uuid

                      offer_details
                      
                      

Object

                      offers
                      
                      

Array of Strings

Offer ID’s passed in transaction

Response Body

                      status
                      
                      

String

error

                      error_message
                      *
                      

String

Mandatory

invalid_card_number

                      error_code
                      *
                      

String

Mandatory

invalid_request

API Latency Guidelines

What is API Latency?

Time taken by the server to respond to the API request.

Average API Percentile Metrics and Recommended Timeout

TP50 (s): This represents the median latency, meaning 50% of all requests are completed in this time or less. It indicates the typical performance experienced by the majority of users.
TP90 (s): This value shows that 90% of requests are completed within this time, leaving 10% of requests that take longer. It gives insight into the performance for a broader set of users, beyond the median.
TP99 (s): This value indicates that 99% of requests finish within this time, with only 1% of requests taking longer. It helps identify outlier cases where latency may become an issue for a small group of users.
TP99.9 (s): This metric captures extreme latency outliers, where only 0.1% of requests take longer than this value. It's useful for understanding edge cases where performance degrades for very few users.

TP99.99 (s): This measures the most rare and severe performance outliers, where just 0.01% of requests exceed this time. Monitoring this helps in addressing the rarest and most critical latency issues that may impact user experience in exceptional scenarios.

Scroll inside to view more

Transaction Percentile	Latency (s)
TP50 (s)em	0.0198
TP90 (s)	0.290
TP99 (s)	0.429
TP99.9 (s)	0.429
Recommended Timeout	1

Have questions?
Need help? Contact support
LLM? Read llms.txt