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

Pre Auth Order+Payment API

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

Only If you are a PCI-compliant merchant, you can integrate with this API.

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

                      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
                      
                      

Boolean

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

Example:- true, false

                      order.metadata.JUSPAY:gateway_reference_id
                      
                      

String

Use this parameter only when you have use case of gateway reference ID. For detailed information check here.

                      metadata.txns.auto_capture
                      
                      

Boolean

The default is set to true. Pass false to for pre-auth orders.

Example:- false,true

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