Process OTP

This will complete the authentication and authorization. It takes OTP as input and returns the transaction response.

Note:

See the Process OTP page in the API Reference section for an official description of this API.

Request

Method	URL
POST	https://api.juspay.in/v2/txns/:id/authenticate

⭣

The request for the Process OTP API consists of one Path parameter: id, and three Form parameters as listed below:

	Field		Type	Description
Header (-u)	your_api_key	*	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.
Path param	id	*	String	Unique id generated for the transaction in a generate OTP API call.
	challenge_id	*	String	Challenge id generated against the transaction in generating OTP API call.
	answer.otp	*	String	OTP to be sent for authenticating the transaction.
	auto_capture		String	Send false if you want to capture at a later stage. The default is true.

* = Required

Example

curl -X POST https://api.juspay.in/v2/txns/:id/authenticate \
-u your_api_key: \
-d "challenge_id=ch_xyz" \
-d "answer.otp=123456"

Response

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

Parameter	Type	Description
id	String	Unique ID generated by Juspay for the transaction.
order_id	String	Unique Identifier for the order provided by you while creating order. Maximum length should be 21 characters.
txn_id	String	Transaction ID for a given order.
status	String	Status of the transaction. If you receive “CHARGED”, then the transaction is successful. “AUTHORIZED” in case if 'auto_capture' is false. 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
gateway	String	Gateway through which authorization process was performed.
created	String	Date/time (ISO representation) when transaction was initiated
resp_code	String	Gateway response code for the transaction.
refunded	Boolean	True if there are any refunds attempted for a given transaction. (Used to enable "refunds" array?)
payment_info:wwwwwwwwn {param1, param2, ....}	Object String	Object containing payment and card details provided during the transaction.

Payment Info Object Parameters:

Field	Type	Description
payment_method_type	String	Must be CARD.
payment_method	String	One of VISA/MASTERCARD/MAESTRO/AMEX/RUPAY.
card:wwwwwwwwwwin {param1, param2, ....}	Object String	Object containing credit/debit card details

Card Object Parameters:

Field	Type	Description
last_four_digits	String	Last four digits of card number
card_isin	String	International Securities Identification Number for card
expiry_month	String	Expiry month of the card (Format: mm) Example: 06
expiry_year	String	Expiry year of the card (Format: yyyy) Example: 2020
name_on_card	String	Card holder name. Should contain alphabetical characters only.
card_type	String	"CREDIT" or "DEBIT"
card_issuer	String	Code for bank that issued the card (Example: "HDFC Bank")
card_brand	String	Brand of card (MASTERCARD, VISA, etc.)
card_reference	String	Reference code for the card
card_fingerprint	String	Fingerprint code for the card
using_saved_card	Boolean	True if using a saved card
saved_to_locker	Boolean	True if card has been saved to locker


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 given order.
challenge_id	String	Unique ID generated for the challenge option
auth_type	String	Type of authentication used (OTP)
card_isin	String	International Securities Identification Number for card
card_issuer_bank_name	String	Code for bank that issued the card (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 for fallback


payment_gateway_response: {param1, param2, ....}	Object String	This will give the payment response received from the gateway

Payment Gateway Response Object Parameters:

Field	Type	Description	Example
txn_id	String	Transaction ID	"11327833"
rrn	String	Authorization Retrieval Reference Number	"502913366745"
resp_message	String	Error message from the gateway in case if the transaction failed.	"Payment Successful"
resp_code	String	Gateway response code for the transaction.	"0"
epg_txn_id	String	Electronic Payment Gateway transaction ID	"1532690566017"
created	String	Date time (ISO representation) when transaction was initiated.	"2020-04-28T06:31:37Z"
auth_id_code	String	Authorization ID Code	"475926"
gateway_response_mapi {param1, param2, ....}	Object String	gateway dependent response parameters


Refunds: [{...},{...},..] wwwwwwwwwwwwwwwww	Array wwwwt	An array of Refund Objects with details of each refund attempted for a given transaction (returned only if the refunded parameter is set to "true".

Refund Object Parameters:

Field	Type	Description
id	String	ID generated for the refund
unique_request_id	Srtring	Unique ID generated for the request
ref	String	Reference number provided by the bank for the refund
amount	Double	Amount refunded (or to be refunded)
created	String	Date time (ISO representation) when transaction was initiated
status	String	Status of the refund. Can be one of PENDING, SUCCESS, FAILURE, MANUAL_REVIEW (see table below for meaning).
error_message	String	Message if error occured
sent_to_gateway	Boolean	Set to 'true' if request was sent to gateway

Status	Meaning
SUCCESS	This means that the refund has been successfully executed.
PENDING	This would mean that the refund has been queued with JusPay or with the downstream system.
FAILURE	We were unable to process the refund successfully. You have to try again with new unique_request_id.
MANUAL_REVIEW	This would mean that the refund request was sent an ambigious response from the payment gateway and the merchant has to manually reconcile it with the payment gateway to get the proper response. Also, any refunds which are in pending for more than 10 days are set for manual review.

Example

{
  "id": "txn_035b4e708d5148478828ea3136a9efd7",
  "order_id": ":order_id",
  "txn_id": ":txn_id",
  "status": "CHARGED",
  "gateway": "RAZORPAY",
  "created": "2017-05-05T12:12:08Z",
  "resp_code": "00",
  "resp_message": "",
  "payment_info": {
    "payment_method_type": "CARD",
    "payment_method": "VISA",
    "card": {
    "last_four_digits": "",
    "card_isin": "400020",
    "expiry_month": "09",
    "expiry_year": "2020",
    "name_on_card": "",
    "card_type": "",
    "card_issuer": "",
    "card_brand": "VISA",
    "card_reference": "",
    "card_fingerprint": "37sug6sns7p8ubota3md74va3u",
    "using_saved_card": false,
    "saved_to_locker": false
    }
  },"payment"  : {
    "authentication": {
    "method": "POST",
    "url": "https://api.juspay.in/v2/txns/:id/authenticate",
    "params": {
            "id"                    : "8646a7a029974fa99995fec00340a507",
            "challenge_id"          : "ch_xyz",
            "auth_type"         : "OTP",
            "card_isin"             : "424242",
            "card_issuer_bank_name" : "AXIS BANK LTD",
            “submit_otp_allowed”    : true,
            “resend_otp_allowed”    : false,
            “fallback_url”          : "https://sandbox.juspay.in/v2/pay/start/guest/eul5g88vzCXbswrHYMh"

    }
    }
   },
  "payment_gateway_response": {
    "created": "2017-05-05T12:12:42Z",
    "txn_id": ":txn_id",
    "rrn": "",
    "epg_txn_id": ":epg_txn_id",
    "auth_id_code": "",
    "resp_code": "00",
    "resp_message": "",
    "gateway_response_map": {
    //gateway dependent response parameters
    }
  },
  "refunds":[ ]
}

{
  "id": "txn_035b4e708d5148478828ea3136a9efd7",
  "order_id": ":order_id",
  "txn_id": ":txn_id",
  "status": "AUTHENTICATION_FAILED",
  "gateway": "RAZORPAY",
  "created": "2017-05-05T12:12:08Z",
  "resp_code": "00",
  "resp_message": "",
  "payment"  : {
    "authentication": {
    "method": "POST",
    "url": "https://api.juspay.in/v2/txns/:id/authenticate",
    "params": {
            "id"                    : "8646a7a029974fa99995fec00340a507",
            "challenge_id"          : "ch_xyz",
            "auth_type"         : "OTP",
            "card_isin"             : "424242",
            "card_issuer_bank_name" : "AXIS BANK LTD",
            “submit_otp_allowed”    : true,
            “resend_otp_allowed”    : false,
            “fallback_url”          : "https://sandbox.juspay.in/v2/pay/start/guest/eul5g88vzCXbswrHYMh"

    }
    }
   },
  "payment_info": {
    "payment_method_type": "CARD",
    "payment_method": "VISA",
    "card": {
    "last_four_digits": "",
    "card_isin": "400020",
    "expiry_month": "09",
    "expiry_year": "2020",
    "name_on_card": "",
    "card_type": "",
    "card_issuer": "",
    "card_brand": "VISA",
    "card_reference": "",
    "card_fingerprint": "37sug6sns7p8ubota3md74va3u",
    "using_saved_card": false,
    "saved_to_locker": false
    }
  },
  "payment_gateway_response": {
    "created": "2017-05-05T12:12:42Z",
    "txn_id": ":txn_id",
    "rrn": "",
    "epg_txn_id": ":epg_txn_id",
    "auth_id_code": "",
    "resp_code": "00",
    "resp_message": "",
    "gateway_response_map": {
    //gateway dependent response parameters
    }
  },
  "refunds":[ ]
}

{ "status": "invalid_request_error",
  "error_code": "invalid",
  "error_message": "Invalid authentication account id."}

{ "status": "error",
  "error_code": "access_denied",
  "error_message": "Invalid Authentication"}