EMV 3DS 2 SDK
The 3DS 2 protocol mandates the integration of an EMV 3DS SDK for processing authentication via in-app flow. This SDK provides capabilities to authenticate processes in the native app UI without redirection to the bank ACS page for cardholder authentication. This improves the overall customer experience. EMV 3DS 2 authentication allows you to:- Collect and pass additional device data to Issuer ACS for risk assessment. In the case of cross-border payments, issuer ACS can use the data passed to decide between frictionless or challenge-based authentication flow.
Integration Steps
Razorpay will provide a ready-to-use 3DS 2 SDK certified by EMVCo. You may use this SDK to process 3DS 2 payment providers, including Razorpay. The SDK-based flow will vary for both Challenge-based and Frictionless authentication flows.Changes Required for Challenged Flow
[Pass additional parameter in Create a Payment API request](#1-pass...
[Collect Device Information](#2-collect-device-information).
[Submit Device Information to Razorpay](#3-submit-device-informatio...
[Present the Challenge Flow to the Cardholder](#4-present-the-chall...
[Verify Payment Status on Razorpay Server](#5-verify-payment-status...
1. Pass Additional Parameter in Create a Payment API request
Pass the following additional parameter in the Create a Payment API request apart from the existing parameters.Request Parameters
authentication
: object Details of the authentication channel.
authentication_channel mandatory
: string The authentication channel for the payment. In the case of SDK-based transaction, the possible value is app. For all other cases, it can be browser.
Response Parameters
message_version
: string The exact protocol version supported by the card.
directory_server_id
: string This is threeDSServerTransID sent by the ACS.
directory_server_public_key
: string Public key for performing authentication.
next
: array A list of action objects available to you to continue the payment process. Present when the payment requires further processing.
action
: string An indication of the next step available to you to continue the payment process.
url
: string URL to be used for the action indicated.
2. Collect Device Information
When you get the action assubmit_3ds_device_information, you will need to start the device fingerprinting process using the 3DS 2 SDK. There are two ways:
- Using Razorpay’s EMVCo SDK
- Using Direct EMVCo SDK
Using Razorpay EMVCo SDK
Follow these steps to initiate the SDK call to collect 3DS 2 device information:Initiate the `get_device_information` method on Razorpay SDK. Razor...
get_device_information method on Razorpay SDK. Razorpay SDK will make required calls to the inherent 3DS 2 SDK.Using the response received in payment create API, pass the followi...
get_device_information method:directory_server_idmessage_versiondirectory_server_public_key
The `get_device_information` method will return the below parameter...
get_device_information method will return the below parameters. You need to pass the same to Razorpay in the next API call. The parameters are:sdk_app_idsdk_transaction_idsdk_ephemeral_public_keydevice_datemessage_version
Using Direct EMVCo SDK
Follow these steps to initiate the SDK call to collect 3DS 2 device information:Create instances of ConfigParameters, locale, and UiCustomization f...
directory_server_id, and the directory_server_public_key parameters returned during the payment create response.Call the initialise method to initialise the 3DS SDK during the App...
Call the `createTransaction` method on SDK by passing the `director...
createTransaction method on SDK by passing the directory_server_id parameter returned during the payment create response.Call the `getProgressView` method on the SDK. This step shows a pro...
getProgressView method on the SDK. This step shows a processing screen to the cardholder.Call the `getAuthenticationRequestParameters` method on the SDK and...
getAuthenticationRequestParameters method on the SDK and obtain the AuthenticationRequestParameters object that contains the following:sdkAppIdsdkTransactionIDsdkEphemeralPublicKeysdkReferenceNumberdeviceDatamessageVersion
3. Submit Device Information to Razorpay
Once the data is collected using the above steps:Make an API call from your backend to submit device data to Razorpay.
Razorpay will initiate an authentication request. If the issuer ban...
If the issuer bank approves frictionless flow, you will receive a s...
Sample Code
Given below is the sample code:Request Parameters
sdk_app_id mandatory
: string App id used by ACS/DS to identify the transaction.
sdk_transaction_id mandatory
: string Transaction id used by ACS/DS to identify the transaction.
sdk_encrypted_data mandatory
: string Encrypted response data sent by DS via ACS.
sdk_reference_number mandatory
: string Reference number used by ACS/DS to identify the transaction.
sdk_ephemeral_public_key mandatory
: object This is the public key used to decrypt the sdk_encrypted_data at our data at our end. It should contain the below fields.
crv mandatory
: string Indicates the curve.
kty mandatory
: string Indicates the key type.
x mandatory
: string X coordinate of the curve.
y mandatory
: string Y coordinate of the curve.
authentication_channel mandatory
: string This value is used for processing the transaction as an sdk-based flow. The constant value should be app for the SDK transaction.
auth_step mandatory
: string This value is an indicator for Razorpay to process the authenticate the payment.
Response Parameters
threeDSServerTransID
: string Sent by DS via ACH to check the validation of the transaction at each step.
acs_transaction_id
: string Transaction id used by ACS to identify the transaction.
acs_reference_number
: string Reference number used by ACS to identify the transaction.
acs_signed_content
: string Signed (encrypted) response sent by ACS.
acs_rendering_type
: string Contains Layout rendering information.
4. Present the Challenge Flow to the Cardholder
In the previous API, if you receive the value ofaction as initiate_challenge_via_sdk, it means that the challenge flow is required.
There are two ways you can use the SDK to process the challenge flow:
- Using Razorpay’s EMVCo SDK
- Using Direct EMVCo SDK
Using Razorpay EMVCo SDK
Given below is the SDK call to be made to collect 3DS 2 device information:- Initiate the
process_challegemethod. - Provide the data received in the previous API response to the SDK. The parameters required are:
directory_server_transaction_idacs_transaction_idacs_reference_numberacs_signed_content3ds_requestor_app_url
3ds_requestor_app_url- You will not get this parameter in the API response, and you need to pass your app redirection URL to this parameter.
challenge_status
Using Standalone EMVCo SDK
Given below is the SDK call to be made to collect 3DS 2 device information:Create an instance of `ChallengeParameters`.
ChallengeParameters.You will need to call the `dochallenge` method.
dochallenge method.Your app provides the following to the SDK:
directory_server_transaction_idacs_transaction_idacs_reference_numberacs_signed_content3ds_requestor_app_urlchallenge_status
Call the `cleanup` method to free up resources.
cleanup method to free up resources.5. Verify Payment Status on Razorpay Server
You can use your existing integration to verify payment status. Such as:- Poll Payment APIs to check the payment status. This API needs to be hit in a cron job, as payment will get authorized once this API is hit for the first time. And the payment status change will show up on subsequent calls.
- Listening to payment callback events or webhooks.
Changes Required for Frictionless Flow
[Pass additional parameter in Create a Payment API](#1-pass-additio...
[Collect Device Information](#2-collect-device-information)
[Submit Device Information](#3-submit-device-information-to-razorpay)
1. Pass Additional Parameter in Create a Payment API Request.
Pass the following additional parameter in the Create a Payment API request apart from the existing request parameters.Request Parameters
authentication
: object Details of the authentication channel.
authentication_channel mandatory
: string The authentication channel for the payment. For SDK-based transactions, the possible value is app. For all other cases, it can be browser.
Response Parameters
network
: string The card’s network value.
message_version
: string The exact protocol version supported by the card.
directory_server_id
: string This is the threeDSServerTransID sent by the ACS.
directory_server_public_key
: string Public key for performing authentication.
2. Collect Device Information
When you get the action assubmit_3ds_device_information, you will need to start the device fingerprinting process using the 3DS 2 SDK. You will call the SDK commands as given below:
There are two ways:
- Using Razorpay’s EMVCo SDK
- Using Direct EMVCo SDK
Using Razorpay EMVCo SDK
Follow these steps to initiate the SDK call to collect 3DS 2 device information:Initiate the `get_device_information` method on Razorpay SDK. Razor...
get_device_information method on Razorpay SDK. Razorpay SDK will make required calls to the inherent 3DS 2 SDK.Using the response received in payment create API, pass the followi...
get_device_information method:directory_server_idmessage_versiondirectory_server_public_key
The `get_device_information` will return the below parameters, and...
get_device_information will return the below parameters, and you need to pass the same to Razorpay in the next API call.sdk_app_idsdk_transaction_idsdk_ephemeral_public_keysdk_reference_numberdevice_datemessage_version
Using Direct EMVCo SDK
Follow these steps to initiate the SDK call to collect 3DS 2 device information:Create instances of ConfigParameters, locale, and UiCustomization f...
directory_server_public_key parameters returned Payment Create response.Call the initialise method to initialise the 3DS SDK during App sta...
Call the `createTransaction` method on SDK by passing the `director...
createTransaction method on SDK by passing the directory_server_id parameter returned in the payment create response.Call the `getProgressView` method on the SDK. This step shows a pro...
getProgressView method on the SDK. This step shows a processing screen to the cardholder.Call the `getAuthenticationRequestParameters` method on the SDK and...
getAuthenticationRequestParameters method on the SDK and obtain the AuthenticationRequestParameters object that contains:sdk_app_idsdk_transaction_idsdk_ephemeral_public_keysdk_reference_numberdevice_datamessage_version
3. Submit Device Information to Razorpay
Once the data is collected using the above steps:Make an API call from your backend to submit the device data to Raz...
Razorpay will initiate an authentication request. If the issuer ban...
If issuer banks approve frictionless flow, then you will get a paym...
Sample Code
Given below is the sample code:Request Parameters
id mandatory
: string Unique identifier of the payment.
sdk_app_id mandatory
: string App id used by ACS/DS to identify the transaction
sdk_transaction_id mandatory
: string Transaction id used by ACS/DS to identify the transaction.
sdk_encrypted_data mandatory
: string Encrypted Response Data sent by DS via ACH.
sdk_reference_number mandatory
: string Reference number used by ACS/DS to identify the transaction.
sdk_ephemeral_public_key mandatory
: string This is the public key used to decrypt the sdk_encrypted_data at our end. It should contain the below fields.
crv mandatory
: string curve.
kty mandatory
: string key type.
x mandatory
: string x coordinate of the curve.
y mandatory
: string y coordinate of the curve.
authentication_channel
: string Constant value should be app for sdk trx. This value is used for processing the transaction as a sdk-based flow.
auth_step
: string Constant value should be 3ds2Auth. This value is an indicator for Razorpay to process the authentication on the payment.
The above response indicates that the issuer bank has approved a frictionless payment flow. You can show a successful payment response to the customer.