EC API

3DS 2.0 Only Authentication Flow

Introduction:

Juspay HyperSDK can be integrated within the merchant application to facilitate native OTP authentication on 3DS2.0 rails. SDK will render native screens on merchant applications and complete authentication with the help of 3DS Server and ACS. Merchants can customize the UI to be rendered as per their needs.

The Authentication only flow from Juspay improves efficiency, and offers a dedicated solution for merchants in need of authentication services, eliminating the additional steps associated with traditional transactions.

Flow explanation:

Diagram:

Image Label Appears here
Image Label Appears here

Steps in the flow:

  • Order creation from Merchant systems

  • Juspay SDK initiation

  • Juspay SDK and Backend to complete authentication along with 3DS Server, ACS Server and send Authentication response to Merchant App

  • Merchant calls /orderstatus API to Juspay Backend to get authentication parameters

    1. Merchant to poll the API Incase a blank response is sent for authentication parameters

    2. Juspay will also send a webhook once authentication is completed

  • Merchant to proceed with Authorization with their respective AuthZ provider (Payment Gateway)

API reference:

S2S Calls:

  1. Order create

  • Request format: Merchant to call Juspay /order create with the below extra parameters so that the txn can be identified as a only Authentication transaction

    • txn_type : AUTHENTICATION

    • acquirer_details : {"acquirerBin":"12345","acquirerMId":"22222","mcc":"3333","merchantName":"easebuzz"}

      • acquirerBin - Acquiring institution identification code as assigned by the DS receiving the AReq message. This field is limited to 11 characters

      • acquirerMerchantId: Acquirer-assigned Merchant identifier. The field is limited to a maximum of 35 characters

      • acquirerCountryCode - This is the code of the country where the acquiring institution is located. The specified length of this field is 3 characters and will accept values according to the ISO 3166-1 numeric three-digit

    • country code

  • Response format: Same as other flows and nothing specific to this flow 

2.Get Order Status

  • Request format: Same as other flows. Nothing specific for this flow

Response format:

  • Terminal status of Order: SUCCESS/FAILED

  • Terminal status of txn: VBVSuccessful/AuthenticationFailed

  • Juspay responds for getOrderStatus API with below Authentication parameters in the second_factor_response block of the response

    • "second_factor_response":
      {

            "eci": "07",

             "cavv": null,

              "threeDSVersion": "2.2.0",

               "threeDSTransStatusReason": "01",

               "threeDSServerTransID": "c10e57e3-7fdd-4f17-b154-1f04515ab426",

                "threeDSTransStatus": "N",

                "cavvAlgorithm": null,

                "threeDSTransId": "3f083000-5050-47a0-b413-f180a490ce85"

              }

  • Meaning of each parameter:

    Scroll inside to view more
    Parameter
    Meaning
    Possible Values
    eci
    Indicates whether AuthN happened through 3DS 2.O or a non authenticated transaction
    05: Authenticated successfully 06: Authentication attempted but not completed 07: Authentication failed
    cavv
    Cryptographic token used to authenticate the transaction
    threeDSVersion
    Indicates the version of 3DS 2.0 being used
    2.1.0, 2.2.0
    threeDSTransStatusReason
    Gives explanation of the transaction status
    01: Authentication failed 02: Unknown device 03: Unsupported device 04: Exceeds number of attempts 05: Authentication expired 06: Transactions not permitted 07: Data Entry error 08: Suspected fraud 09: Transaction not recognised 10: Others
    threeDSServerTransID
    Unique identifier to identify the transaction in the server
    uuid
    threeDSTransStatus
    Indicates the outcome of the transaction
    Y: Authentication successful. Merchant can proceed with Authorization N: Authentication failed. Merchant to notify customer and attempt retry of authentication U: Unable to authenticate. Merchant to retry or log failure A: Attempts authentication R: Authentication rejected. Merchant should not retry and tell customer to use a different payment method
    cavvAlgorithm
    Algorithm used to create the CAVV
    0 – HMAC-SHA-1 (Legacy) 1 – HMAC-SHA-256 (Common in 3DS 2.0) 2 – HMAC-SHA-384 3 – HMAC-SHA-512 4 – Elliptic Curve (EC)
    threeDSTransId
    Unique identifier for each 3DS 2.0 transaction
    uuid

    1. Note: 

      1. Above second_factor_response can come as blank from Juspay. In this case merchant should poll Juspay upto 15 mins to get actual values

      2. Juspay will also send a webhook for the AuthN response once it is complete

      3. Reference and error codes: https://docs.juspay.in/ec-api/docs/base-integration/order-status-apilink icon

SDK Calls:

sdk/initiate

  • Request:

    Sample Request
    Sample Request

  • Response

    Sample response
    Sample response

Authentication request, response format:

  • When to call the Authentication request: This should be called once the user has clicked on proceed to pay in the payment page

    1. AuthN request should be sent after orderCreate and sdk/initiate has finished

  • Request format:

    • New card flow:

      New card flow
      New card flow

    • Tokenized card flow:

      Saved card flow
      Saved card flow

  • Response format:

    Response format
    Response format

  • Error response for Authentication:

    Failure response
    Failure response

    Setting up the SDK:

    Add buildscript repository and dependency in your root build.gradle file:

    Setting up sdk
    Setting up sdk

    Add the SDK maven repository to the allprojects repository in the same root build.gradle:

    build.gradle
    build.gradle

    Apply the plugin in your app’s build.gradle:

    Apply plugin
    Apply plugin

    Add the following block at the end of the same app’s build.gradle file:

    End of build.gradle
    End of build.gradle

Last updated 1 year ago