Welcome to the OTPLESS Headless SDK documentation! This guide will walk you through the steps to integrate our SDK into your Android project, providing you with the flexibility to create custom UI elements for your authentication flows.
Requirements
The compileSdk version should be 35.
The minimum SDK version supported by the SDK is 21.
The kotlin version should be 1.9.0 and above.
The gradle version should be 8.3.1 and above.
This is the new Headless authentication SDK that is significantly faster and more robust than the previous version. This upgrade enhances performance, reliability, and security, ensuring a seamless authentication experience, along with a seamless integration process. We strongly recommend migrating to the new SDK for improved efficiency and better support. To migrate from the old SDK, remove the previous SDK dependency and integration and follow the below mentioned steps.
Make sure that Silent Network Authentication is enabled on the OTPLESS dashboard.
Once you have successfully integrated OTPLESS Android SDK in your application, you only have to add the following line in your app’s AndroidManifest file in the <application> tag:
Now, let’s implement a callback method to handle the response from the OTPLESS SDK:
Copy
Ask AI
private fun onOtplessResponse(response: OtplessResponse) { OtplessSDK.commit(response) when (response.responseType) { ResponseTypes.SDK_READY -> { // SDK has been initialized successfully, you may enable your continue button or proceed with user authentication. } ResponseTypes.FAILED -> { // Notify that the initialization failed if (response.statusCode == 5003) { // SDK initialization failed, please try to initialize the SDK again } } ResponseTypes.INITIATE -> { // notify that authentication has been initiated if (response.statusCode != 200) { handleInitiateError(response); } else { val authType = response.response?.optString("authType") // This is the authentication type if (authType == "OTP") { // Take user to OTP verification screen } else if (authType == "SILENT_AUTH") { // Handle Silent Authentication initiation by showing loading status for SNA flow. } } } ResponseTypes.OTP_AUTO_READ -> { val otp = response.response?.optString("otp") if (!otp.isNullOrBlank()) { // Autofill the OTP in your TextField/EditText } } ResponseTypes.VERIFY -> { // notify that verification has failed. if (response.response?.optString("authType") == "SILENT_AUTH") { if (response.statusCode == 9106) { // Silent Authentication and all fallback authentication methods in SmartAuth have failed. // The transaction cannot proceed further. // The transaction cannot proceed further. Handle the scenario to gracefully exit the authentication flow } else { // Silent Authentication failed. If SmartAuth is enabled, the INITIATE response will include the next available authentication method configured in the dashboard. } } else { handleVerifyError(response) } } ResponseTypes.DELIVERY_STATUS -> { // This function is called when delivery is successful for your authType. val authType = response.response?.optString("authType") // It is the authentication type (OTP, MAGICLINK, OTP_LINK) for which the delivery status is being sent val deliveryChannel = response.response?.optString("deliveryChannel") // It is the delivery channel (SMS, WHATSAPP, etc) on which the authType has been delivered } ResponseTypes.FALLBACK_TRIGGERED -> { // A fallback occurs when an OTP delivery attempt on one channel fails, // and the system automatically retries via the subsequent channel selected on Otpless Dashboard. // For example, if a merchant opts for SmartAuth with primary channal as WhatsApp and secondary channel as SMS, // in that case, if OTP delivery on WhatsApp fails, the system will automatically retry via SMS. // The response will contain the deliveryChannel to which the OTP has been sent. if (response.response != null) { val newDeliveryChannel = response.response.optString("deliveryChannel"); // This is the deliveryChannel to which the OTP has been sent } } ResponseTypes.ONETAP -> { // final response with token val token = response.response?.optJSONObject("data")?.optString("token") if (!token.isNullOrBlank()) { // Process token and proceed. } } }}
Well done! You have completed the foundational setup of the SDK. Now, let’s move to the next step and understand how to initiate and verify different authentication modes.
Choose the authentication mode you want to integrate from the options below:
Phone Authentication 📱
Phone authentication allows users to verify their identity using their phone number. Merchants can choose from various authentication methods:
Silent Authentication (SNA) – Automatically verifies the user without requiring OTP or MAGICLINK.
OTP on Desired Channel – Sends a one-time password (OTP) via SMS, WhatsApp, or another preferred channel.
Magic Link – Sends a link that users can click to authenticate.
SNA + OTP – Uses silent authentication first and falls back to OTP if needed.
OTP + Magic Link – Sends both an OTP and a magic link, allowing users to authenticate via either method.
Copy
Ask AI
final OtplessRequest otplessRequest = new OtplessRequest();otplessRequest.setPhoneNumber("PHONE_NUMBER", "COUNTRY_CODE");OtplessSDK.INSTANCE.startAsync(otplessRequest, this::onOtplessResponse);
To verify the OTP entered by the user, use the verify method with the necessary parameters. Verifying OTP is required only in case of OTP authentication. No need to verify OTP in case of MAGICLINK.
Copy
Ask AI
final OtplessRequest otplessRequest = new OtplessRequest();otplessRequest.setPhoneNumber("PHONE_NUMBER", "COUNTRY_CODE");otplessRequest.setOtp("XXXXXX");OtplessSDK.INSTANCE.startAsync(otplessRequest, this::onOtplessResponse);
Phone Authentication 📱
Phone authentication allows users to verify their identity using their phone number. Merchants can choose from various authentication methods:
Silent Authentication (SNA) – Automatically verifies the user without requiring OTP or MAGICLINK.
OTP on Desired Channel – Sends a one-time password (OTP) via SMS, WhatsApp, or another preferred channel.
Magic Link – Sends a link that users can click to authenticate.
SNA + OTP – Uses silent authentication first and falls back to OTP if needed.
OTP + Magic Link – Sends both an OTP and a magic link, allowing users to authenticate via either method.
Copy
Ask AI
final OtplessRequest otplessRequest = new OtplessRequest();otplessRequest.setPhoneNumber("PHONE_NUMBER", "COUNTRY_CODE");OtplessSDK.INSTANCE.startAsync(otplessRequest, this::onOtplessResponse);
To verify the OTP entered by the user, use the verify method with the necessary parameters. Verifying OTP is required only in case of OTP authentication. No need to verify OTP in case of MAGICLINK.
Copy
Ask AI
final OtplessRequest otplessRequest = new OtplessRequest();otplessRequest.setPhoneNumber("PHONE_NUMBER", "COUNTRY_CODE");otplessRequest.setOtp("XXXXXX");OtplessSDK.INSTANCE.startAsync(otplessRequest, this::onOtplessResponse);
Email Authentication 📧
Email authentication verifies users using their email address. Merchants can choose from:
OTP via Email – Sends a one-time password to the user’s email.
Magic Link – Sends a clickable authentication link to the email.
OTP + Magic Link – Provides both options for flexibility.
Copy
Ask AI
final OtplessRequest otplessRequest = new OtplessRequest(); otplessRequest.setEmail("EMAIL_INPUT"); OtplessSDK.INSTANCE.startAsync(otplessRequest, this::onOtplessResponse);
To verify the OTP entered by the user, use the verify method with the necessary parameters. Verifying OTP is required only in case of OTP authentication. No need to verify OTP in case of MAGICLINK.
Copy
Ask AI
final OtplessRequest otplessRequest = new OtplessRequest();otplessRequest.setEmail("EMAIL_INPUT");otplessRequest.setOtp("XXXXXX");OtplessSDK.INSTANCE.startAsync(otplessRequest, this::onOtplessResponse);
OAuth Authentication 🔑
OAuth allows users to authenticate using third-party services like Google, GitHub, or WhatsApp. Instead of entering credentials manually, users can log in using their existing accounts, streamlining the authentication process.
Copy
Ask AI
final OtplessRequest otplessRequest = new OtplessRequest();otplessRequest.setChannelType(OtplessChannelType.SOCIAL_CHANNEL_NAME);OtplessSDK.INSTANCE.startAsync(otplessRequest, this::onOtplessResponse);