Juspay Developer Guide

Welcome to the Juspay Developer Guide. You'll find comprehensive guides and documentation to help you start working with Juspay Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Start Authentication

This will start the authentication by sending the OTP on the registered mobile number for a given card detail. To initiate the authentication, the first step is to create order at our end. For order creation API, please check here.

Request

TypeParamsValuesDescription
HEADERapi_keystringAPI 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.
POSTorder_idstringYour order_id pertaining to the order for which the payment is started.
merchant_idstringID of the merchant_account that you hold with us.
payment_method_typestringMust be CARD.
payment_method[optional]stringOne 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[optional]stringCase 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_numberstringA valid credit/debit card number
name_on_card[optional]stringCardholder name. Should contain alphabetical characters only.
card_exp_yearstringRepresents the expiry year of the card as YY (two digits only)
card_exp_monthstringRepresents the expiry month of the card as MM (two digits only)
card_security_codeStringCVV 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.
formatstringAlways set this to JSON.
auth_typestringThis should be “OTP” for direct authentication.
gateway_id[optional]stringA 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[optional]stringId 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.

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, we request please provide these values while order creation.
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

{
   "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"
}
Response ParamsValuesDescription
order_idstringOrderID for which the payment is being started.
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.
paymentstringContains the payment authentication details.
authenticationstringContains the authentication details.
methodstringHTTP Method for authentication. Can be one of GET or POST
urlstringURL to which the user has to be taken for completing the authentication
paramsobjectPresent only when the method is POST. Parameter map that has to be sent along with the URL for authentication.
idstringUnique id generated for the transaction.
challenge_idstringAuthentication id generated against the transaction for a given order.
auth_methodstringAuthentication 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.
times_otp_sentstringNumber of times OTP sent.
max_otp_send_limitstringMaximum limit for sending otp.
current_attemptstringCurrent attempt for OTP validation.
max_attemptsstringMaximum number of time OTP validation can be done for a given transaction.

Updated 3 months ago


Start Authentication


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.