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

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.

See the Start Authentication page in the API Reference section for an official description of this API.


The request consists of Payment Method Details, Card Details, and other parameters as listed below.     (click to open tables)
  Payment Method Details:
order_id*StringYour order_id pertaining to the order for which the payment is started.
merchant_id*StringID of the merchant_account that you hold with us.
payment_method_type*StringMust be CARD.
payment_methodStringOne 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.
format*StringAlways set this to JSON.
  * = Required
  Card Details:
card_tokenStringCase 1: If the token is obtained using the /card/list API. If you send this parameter, then card_number, name_on_card, card_exp_year, and card_exp_month fields are not required.
Case 2: If the token is generated using the /card/tokenize API, then card_number,name_on_card, card_exp_year, card_exp_month and card_security_code fields are not required.
card_number*StringA valid credit/debit card number. Not required if card token is used.
name_on_cardStringCard holder name. Should contain alphabetical characters only.
card_exp_year*StringRepresent the expiry year of the card as YY (two digits only)
card_exp_month*StringRepresent the expiry month of the card as MM (two digits only)
card_security_code*StringCVV of the card. Usually three digits.
save_to_lockerBooleanThis 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.
* = Conditionally required if card_token is not used.
Other Parameters:
API key can be obtained from https://merchant.juspay.in/settings/api-key. Provide your API key as the basic auth username value. You do not need to provide a password.
auth_type*StringThis should be “OTP” for direct authentication.
auth_account_idStringId 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 for this here.
Note: If you’re using a payment aggregator for the direct otp feature, you need not to pass it.
gateway_idStringA 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.
    * = Required


// A regular card transaction
curl -X POST https://api.juspay.in/txns -u your_api_key: \
-d "order_id=:order_id" \
-d "merchant_id=:merchant_id" \
-d "payment_method_type=CARD" \
-d “payment_method=MASTERCARD" \
-d "card_number=4242424242424242" \
-d "card_exp_month=01" \
-d "card_exp_year=21" \
-d "card_security_code=123" \
-d "name_on_card=Name" \
-d "save_to_locker=true" \
-d "format=json" \
-d "auth_type=OTP"

// A Stored card transaction
curl -X POST https://api.juspay.in/txns \
-u your_api_key: \
-d "order_id=:order_id" \
-d "merchant_id=:merchant_id" \
-d "payment_method_type=CARD" \
-d "card_token=:card_token" \
-d "format=json" \
-d "auth_type=OTP" 


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, so please provide these values while creating order.

curl https://api.juspay.in/order/create \
    -u your_api_key: \
    -d "order_id=testotp1" \
    -d "amount=1.00" \
    -d "ip_address=" \
    -d "user_agent=Chrome"


The response for the Start Authentication API consists of the following parameters and objects:     (click to open table)
order_idStringOrder ID for which the payment is being started. This unique Order ID was provided by you while creating order.
txn_idStringTransaction ID for the payment attempt.
txn_uuidStringUnique ID for the payment attempt to be used in /authenticate and /resend API calls.
statusStringStatus of the transaction. PENDING_VBV indicates that the transaction requires authentication to complete. Please do not validate this at your end.
  Status codes and meaning







Newly created order
Successful transaction
In cases where 'auto_capture' is false
Authentication is in progress
User did not complete authentication
User completed authentication, but
bank refused the transaction
User input is not accepted by the
underlying PG
Transaction status is pending from bank
    {method, url, params: {...}}
Returned parameters needed for completing the authentication
   Payment Authentication Object Parameters:
methodStringHTTP Method for authentication. Can be one of GET or POST (See redirection instructions in the "Handling the Redirection Method" section.)
urlStringURL to which the user has to be taken to for completing the authentication
   {param1, param2, ....}
Present only when the method is POST. This a mapping via a list of key:value pairs that must be sent along with the URL for authentication. Do not hardcode the params in your client * Never assume that you will receive param “x” or param “y”. This is completely dynamic and will vary on a case by case basis.
  Params Object Parameters:
idStringUnique ID generated by Juspay for the transaction.
challenge_idStringAuthentication ID generated against the transaction for a given order.
auth_typeStringAuthentication method used. In this case, it’s ‘OTP’
card_isinStringCard first 6 digits.
card_issuer_bank_nameStringIssuer name of the card used for the transaction.
(Example: "HDFC Bank")
submit_otp_allowedBooleanTrue if OTP can be submitted via gateway
resend_otp_allowedBooleanTrue if OTP can be resent via gateway
fallback_urlStringURL to be used as fallback
times_otp_sent  *StringNumber of times OTP sent
max_otp_send_limit  *StringMaximum limit for sending OTP
current_attempt  *StringCurrent attempt for OTP validation.
max_attempts  *StringMaximum number of time OTP validation can be done for a given transaction.
    Parameters marked with a red star (*) were listed in table, but not shown in response below.


   "order_id" : ":order_id",
   "txn_id"   : ":txn_id",
   "status"   : "PENDING_VBV",
   "payment"  : {
    "authentication": {
    "method": "POST",
    "url": "https://api.juspay.in/v2/txns/:id/authenticate",
    "params": {
            "id"                    : "eul5g88vzCXbswrHYMh",
            "challenge_id"          : "ch_xyz",
            "auth_type"         : "OTP",
            "card_isin"             : "424242",
            "card_issuer_bank_name" : "AXIS BANK LTD",
            “submit_otp_allowed”    : true,
            “resend_otp_allowed”    : true,
            “fallback_url”          : "https://sandbox.juspay.in/v2/pay/start/guest/eul5g88vzCXbswrHYMh?fallback=true"
    "txn_uuid": "eul5g88vzCXbswrHYMh",
    "txn_id": "paypal-1551359984-1",
    "status": "PENDING_VBV",
    "payment": {
        "authentication": {
            "url": "https://sandbox.juspay.in/v2/pay/start/guest/eul5g88vzCXbswrHYMh",
            "method": "GET"
    "order_id": "1551359984"
  "status": "invalid_request_error",
  "error_code": "invalid",
  "error_message": "Invalid authentication account id."
  "status": "error",
  "error_code": "access_denied",
  "error_message": "Invalid Authentication"