--- page_title: Start Authentication product: API Reference page_source: https://juspay.io/in/docs/api-reference/docs/direct-otp/start-authentication openapi: https://juspay.io/in/docs/api/swagger?document=https%3A%2F%2Fjuspay.io%2Fin%2Fdocs%2Fapi-reference%2Fdocs%2Fdirect-otp%2Fstart-authentication llms_txt: https://juspay.io/in/docs/llms.txt product_llms_txt: https://juspay.io/in/docs/api-reference/llms.txt --- ## API Version: default # 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](https://docs.juspay.in/api-reference/docs/express-checkout/create-order-api). > **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"` ## Endpoints: - Sandbox: https://sandbox.juspay.in/txns - Production: https://api.juspay.in/txns ## Request Type: POST ## Content-Type: application/json ## Authorization: #### Basic Auth: Consists of two parts. * Username: API Key obtained from Juspay dashboard * Password: Empty string Example:-MUQ2QUZEQzhFQTY0OUU5QTIxQzNFNTQwNkFDMEZCOg== - Value: MUQ2QUZEQzhFQTY0OUU5QTIxQzNFNTQwNkFDMEZCOg== - Tags: Base64 Encoded Username:Password, Required ## Headers: #### Content-Type: application/x-www-form-urlencoded - Tags: String, Mandatory #### x-routing-id: 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. - Value: customer_1122 - Tags: String, Required ## Sample Code Snippets: ### Sample Request: #### Request - New Card Code Snippet: ```request - new card curl -X POST https://api.juspay.in/txns -u your_api_key: \ -H 'x-routing-id: customer_1122'\ -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" ``` #### Request - Saved Card Code Snippet: ```request - saved card curl -X POST https://api.juspay.in/txns \ -u your_api_key: \ -H 'x-routing-id: customer_1122'\ -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" ``` ### Sample Response: #### 200 - OTP Succeeded: ```json { "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" : "eul5g88xxxxxswrHYMh", "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://api.juspay.in/v2/pay/start/guest/eul5g88xxxxxswrHYMh?fallback=true" } } } } ``` #### 200 - OTP Fails: ```plaintext { "txn_uuid": "eul5g88vzCXbswrHYMh", "txn_id": "paypal-1551359984-1", "status": "PENDING_VBV", "payment": { "authentication": { "url": "https://api.juspay.in/v2/pay/start/guest/eul5xxxxxCXbswrHYMh", "method": "GET" } }, "order_id": "1551359984" } ``` ## Body Parameters: ### Basic Parameters: #### order_id: - Description: Your order_id pertaining to the order for which the payment is started. - Value: value - Tags: String, Mandatory #### merchant_id: - Description: ID of the merchant_account that you hold with us. - Tags: String, Mandatory #### payment_method_type: - Description: Must be CARD. - Tags: String, Mandatory #### payment_method: - Description: 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. - Tags: String #### card_token: - Description: 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. - Tags: String #### card_number: - Description: A valid credit/debit card number - Tags: String, Mandatory #### name_on_card: - Description: Cardholder name. Should contain alphabetical characters only. - Tags: String #### card_exp_year: - Description: Represents the expiry year of the card as YY (two digits only) - Tags: String, Mandatory #### card_exp_month: - Description: Represents the expiry month of the card as MM (two digits only) - Tags: String, Mandatory #### card_security_code: - Description: CVV of the card. Usually three digits. - Tags: String, Mandatory #### save_to_locker: - Description: 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. - Tags: Boolean, Mandatory #### format: - Description: Always set this to JSON. - Tags: String, Mandatory #### auth_type: - Description: This should be “OTP” for direct authentication. - Tags: String, Mandatory #### gateway_id: - Description: 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. - Tags: String #### auth_account_id: - Description: 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. - Tags: String ## API Responses: ### 200: #### order_id: - Description: OrderID for which the payment is being started. - Tags: String #### txn_id: - Description: Transaction ID for the payment attempt. - Tags: String #### txn_uuid: - Description: Unique ID for the payment attempt to be used in /authenticate and /resend API calls. - Tags: String #### status: - Description: Status of the transaction. PENDING_VBV indicates that the transaction requires authentication to complete. Please do not validate this at your end. - Tags: String #### payment: - Description: Contains the payment authentication details. - Tags: String #### authentication: - Description: Contains the authentication details. - Tags: String #### method: - Description: HTTP Method for authentication. Can be one of GET or POST - Tags: String #### url: - Description: URL to which the user has to be taken for completing the authentication - Tags: String #### params: - Description: Present only when the method is POST. Parameter map that has to be sent along with the URL for authentication. - Tags: object #### id: - Description: Unique id generated for the transaction. - Tags: String #### challenge_id: - Description: Authentication id generated against the transaction for a given order. - Tags: String #### auth_method: - Description: Authentication method used. In this case, it’s ‘OTP’ - Tags: String #### card_isin: - Description: Card first 6 digits. - Tags: String #### card_issuer_bank_name: - Description: Issuer name of the card used for the transaction. - Tags: String #### times_otp_sent: - Description: Number of times OTP sent. - Tags: String #### max_otp_send_limit: - Description: Maximum limit for sending otp. - Tags: String #### current_attempt: - Description: Current attempt for OTP validation. - Tags: String #### max_attempts: - Description: Maximum number of time OTP validation can be done for a given transaction. - Tags: String ### 400: #### status: - Description: invalid_request_error - Tags: String #### error_code: - Description: invalid - Tags: String #### error_message: - Description: Invalid authentication account id - Tags: String ### 401: #### status: - Description: error - Tags: String #### error_code: - Description: access_denied - Tags: String #### error_message: - Description: Invalid Authentication - Tags: String --- ## See Also - [Check Eligibility](https://juspay.io/in/docs/api-reference/docs/direct-otp/check-eligibility) - [Process OTP](https://juspay.io/in/docs/api-reference/docs/direct-otp/process-otp)