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:

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

Request

Method	URL
POST	https://api.juspay.in/txns

The request consists of Payment Method Details, Card Details, and other parameters as listed below. (click to open tables)

Payment Method Details:

Field		Type	Description
order_id	*	String	Your `order_id` pertaining to the order for which the payment is started.
merchant_id	*	String	ID of the merchant_account that you hold with us.
payment_method_type	*	String	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.
format	*	String	Always set this to JSON.

* = Required

Card Details:

Field		Type	Description
card_token		String	Case 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	*	String	A valid credit/debit card number. Not required if card token is used.
name_on_card		String	Card holder name. Should contain alphabetical characters only.
card_exp_year	*	String	Represent the expiry year of the card as YY (two digits only)
card_exp_month	*	String	Represent the expiry month of the card as MM (two digits only)
card_security_code	*	String	CVV of the card. Usually three digits.
save_to_locker		Boolean	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.

* = Conditionally required if card_token is not used.

Other Parameters:

	Field		Type	Description
-u	api_key	*	Header String	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	*	String	This should be “OTP” for direct authentication.
	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 for this here. Note: If you’re using a payment aggregator for the direct otp feature, you need not to pass it.
	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.

* = Required

Example

// 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"

📘
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, so please provide these values while creating order.
Eg.
curl https://api.juspay.in/order/create \
    -u your_api_key: \
    -d "order_id=testotp1" \
    -d "amount=1.00" \
    -d "ip_address=127.0.0.1" \
    -d "user_agent=Chrome"

Response

The response for the Start Authentication API consists of the following parameters and objects: (click to open table)

Parameter	Type	Description
order_id	String	Order ID for which the payment is being started. This unique Order ID was provided by you while creating order.
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. Status codes and meaning 10 21 24 23 26 27 22 28 NEW Newly created order CHARGED Successful transaction AUTHORIZED In cases where 'auto_capture' is false PENDING_VBV Authentication is in progress AUTHENTICATION_FAILED User did not complete authentication AUTHORIZATION_FAILED User completed authentication, but bank refused the transaction JUSPAY_DECLINED User input is not accepted by the underlying PG AUTHORIZING Transaction status is pending from bank


payment.authenticationwwwi {method, url, params: {...}}	Object String	Returned parameters needed for completing the authentication

Payment Authentication Object Parameters:

Parameter	Type	Description
method	String	HTTP Method for authentication. Can be one of GET or POST (See redirection instructions in the "Handling the Redirection Method" section.)
url	String	URL to which the user has to be taken to for completing the authentication
params:wwwwwwwwwwi {param1, param2, ....}	Object String	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:

Field	Type	Description
id	String	Unique ID generated by Juspay for the transaction.
challenge_id	String	Authentication ID generated against the transaction for a given order.
auth_type	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. (Example: "HDFC Bank")
submit_otp_allowed	Boolean	True if OTP can be submitted via gateway
resend_otp_allowed	Boolean	True if OTP can be resent via gateway
fallback_url	String	URL to be used as fallback
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.

Parameters marked with a red star (*) were listed in table, but not shown in response below.

Example

{
   "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"
}