Body
Start Authentication
This will start the authentication by sending the OTP on the registered mobile number for a given card's details. To initiate the authentication, the first step is to create order at our end. For order creation API, please check here
.
Note
You may get either direct OTP response or 3DS response (if underlying PG failover to 3DS)
In the case of onstage, they require user_agent & ip_address while starting the authentication, we request please provide these values while order creation.
"ip_address=127.0.0.1"
"user_agent=Chrome"
Request
Response
API Endpoints
Sandbox Link
POST
https://sandbox.juspay.in/txns
Production Link
POST
https://api.juspay.in/txns
Authorization Header
Basic Auth
*
Base64 Encoded Username:Password
Required
Consists of two parts.
Username: API Key obtained from Juspay dashboard
Password: Empty string
Example:-
MUQ2QUZEQzhFQTY0OUU5QTIxQzNFNTQwNkFDMEZCOg==
Headers
Content-Type
*
String
Mandatory
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
Basic Parameters
order_id
*
String
Mandatory
Your order_id pertaining to the order for which the payment is started.
merchant_id
*
String
Mandatory
ID of the merchant_account that you hold with us.
payment_method_type
*
String
Mandatory
Must be CARD.
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
Case 1:If the token is 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.
Case 2: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
Mandatory
A valid credit/debit card number
name_on_card
String
Cardholder name. Should contain alphabetical characters only.
card_exp_year
*
String
Mandatory
Represents the expiry year of the card as YY (two digits only)
card_exp_month
*
String
Mandatory
Represents the expiry month of the card as MM (two digits only)
card_security_code
*
String
Mandatory
CVV of the card. Usually three digits.
save_to_locker
*
Boolean
Mandatory
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.
format
*
String
Mandatory
Always set this to JSON.
auth_type
*
String
Mandatory
This should be “OTP” for direct authentication.
gateway_id
String
A gateway id through which the authorization will be performed after successful authentication. Complete mapping for “gateway_id” can be found here: Gateway mapping
Note: If you’re using a payment aggregator for the direct OTP feature, you need not to pass it.
auth_account_id
String
Id of the provider account to be used for authentication. This will be generated by juspay after the successful configuration of providers account at Juspay’s end. You can find the setting’s for this here.
Note: If you’re using a payment aggregator for the direct otp feature, you need not to pass it.
200 : Success
Response Body
order_id
String
OrderID for which the payment is being started.
txn_id
String
Transaction ID for the payment attempt.
txn_uuid
String
Unique ID for the payment attempt to be used in /authenticate and /resend API calls.
status
String
Status of the transaction. PENDING_VBV indicates that the transaction requires authentication to complete. Please do not validate this at your end.
payment
String
Contains the payment authentication details.
authentication
String
Contains the authentication details.
method
String
HTTP Method for authentication. Can be one of GET or POST
url
String
URL to which the user has to be taken for completing the authentication
params
object
Present only when the method is POST. Parameter map that has to be sent along with the URL for authentication.
id
String
Unique id generated for the transaction.
challenge_id
String
Authentication id generated against the transaction for a given order.
auth_method
String
Authentication method used. In this case, it’s ‘OTP’
card_isin
String
Card first 6 digits.
card_issuer_bank_name
String
Issuer name of the card used for the transaction.
times_otp_sent
String
Number of times OTP sent.
max_otp_send_limit
String
Maximum limit for sending otp.
current_attempt
String
Current attempt for OTP validation.
max_attempts
String
Maximum number of time OTP validation can be done for a given transaction.
400 : Invalid Input data
Response Body
status
String
invalid_request_error
error_code
String
invalid
error_message
String
Invalid authentication account id
401 : Authentication Failed
Response Body
status
String
error
error_code
String
access_denied
error_message
String
Invalid Authentication
Have questions?
- Need help? Contact support
- LLM? Read llms.txt