Biometric/Pin
Cotter's Android SDK helps you easily add a Biometric prompt or PIN fallback to your app. This is useful for protecting transactions or sensitive information like medical records.
There are major updates planned for this feature. Contact us in Slack so we can help you prepare for it.
Enabling PIN and Biometric using Cotter's Android SDK consists of:
- 1.Initializing Cotter
- 2.Calling functions to start Pin Enrollment and Biometric Enrollment
- 3.Verify Biometric or PIN before a transaction
- 4.Enabling and disabling Biometric or PIN in Settings

PIN and Biometric using Cotter's Android SDK
- 2.
- 3.
- 4.
- 5.
- 6.
Add JitPack repository your project level
build.gradle
at the end of repositories.build.gradle
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}
Add the Cotter's SDK as a dependency in your app level
build.gradle
.android {
...
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
dependencies {
...
implementation 'com.github.cotterapp:android-sdk:0.3.2'
}
Then sync your gradle files.
You need to set allowed methods for authenticating your users. To allow
PIN
and BIOMETRIC
, go to https://dev.cotter.app/rules
Set both Biometric and PIN to be allowed
Remember to set the correct Project in the dropdown list.
Your server should do this request to Cotter's server during Registration.
Request
Response
curl -XPOST \
-H 'API_KEY_ID: <your key id>' \
-H 'API_SECRET_KEY: <your secret key>' \
-H "Content-Type: application/json" \
-d '{"client_user_id": "<Your User Identifier (string)>"}' \
'https://www.cotter.app/api/v0/user/create'
{
"ID": "9449e9e9-00e0-4d6b-a4b6-28c5b22b0b0f",
"created_at": "2020-01-21T12:40:21.200727668Z",
"update_at": "2020-01-21T12:40:21.200727668Z",
"deleted_at": null,
"issuer": "<your key ID>",
"client_user_id": "<Your User Identifier (string)>",
"enrolled": [],
"default_method": null
}
To retrieve user's data:
Request
Response
curl -XGET \
-H 'API_KEY_ID: <your key id>' \
-H 'API_SECRET_KEY: <your secret key>' \
'https://www.cotter.app/api/v0/user/:your_user_id'
{
"ID": "9449e9e9-00e0-4d6b-a4b6-28c5b22b0b0f",
"created_at": "2020-01-21T12:40:21.200727668Z",
"update_at": "2020-01-21T12:40:21.200727668Z",
"deleted_at": null,
"issuer": "<your key ID>",
"client_user_id": "<Your User Identifier (string)>",
"enrolled": ["PIN", "BIOMETRIC"],
"default_method": "BIOMETRIC"
}
You can now use the SDK to enroll and verify Biometric and PIN for the user you just created.
In your MainActivity, initialize Cotter with API keys, Cotter's URL to use (prod/test), and your User ID.
Production Endpoint:
https://www.cotter.app/api/v0
Cotter.init(
this.getApplicationContext(),
"https://www.cotter.app/api/v0",
"<User ID>",
"<API_KEY_ID>",
"<API_SECRET_KEY>"
);
Example:
MainActivity.java
public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
...
Cotter.init(
this.getApplicationContext(),
"https://www.cotter.app/api/v0",
"588d6f67-0981-4718-899b-bcd512de1aca",
"w4FK6Zz0XIhtGY3o5biI");
}
...
to enroll both Biometric and PIN, start the
PinEnrollment
flow in your Activity, pass in the Callback
Screen, and the Event
Tag. Event
Tag is used for your own logging, for example, a pin enrollment event can be called "PIN_ENROLLMENT_ANDROID"
to tag a pin enrollment event from an Android device.Cotter.PinEnrollment.startFlow(view, CallBack.class, "EVENT TAG");
Example:
// Inside your app, use a button onClick that calls
// openEnroll to start the flow
public void openEnrollment(View view) {
Cotter.PinEnrollment.startFlow(view, Dashboard.class, "PIN_BIO_ENROLLMENT");
}
After entering the PIN, the user will automatically be prompted to Enroll Biometrics if the device supports it. Entering a PIN is required as a fallback method.

PinEnrollment Flow
The
PinVerification
flow will automatically prompt for Biometric Verification if the user's device has an enrolled biometric, otherwise, it will fallback to entering PIN. Starting the PinVerification
flow is exactly the same as starting the PinEnrollment
flow.Cotter.setOnResetPin(new PinResetInterface() {
@Override
public void onResetPin(User user, Callback callback) {...}
})
Cotter.PinVerification.startFlow(view, CallBack.class, "EVENT TAG");
In the verification page, there is a button called
Forgot PIN
. This is used to send a verification code to allow the user to reset their PIN.setOnResetPin
is used to set a callback function that will be called to reset the pin. You need to provide a function that follows the PinResetInterface
. This function should call your server to initiate the PIN reset request.- 1.Based on the currently logged-in user, find out the user's Email and name
- 2.
- 3.Receive the response from Cotter which contains the fields
success
,challenge_id
,challenge
- 4.Call the
callback.onSuccess
with aJSONObject
containing the following JSON object:
{
"success": true, // from the response from the Reset PIN API
"challenge_id": 123, // from the response from the Reset PIN API
"challenge": "abcde12345", // from the response from the Reset PIN API
"sending_method": "EMAIL",
"sending_destination": "[email protected]"
}
Example:
// In onCreate, set the onResetPin callback
protected void onCreate(Bundle savedInstanceState) {
Cotter.setOnResetPin(new PinResetInterface() {
@Override
public void onResetPin(User user, Callback callback) {
// 1. Call your server
// 2. Get the response from your server
// 3. Construct a JSONObject and pass it to callback.onSuccess
JSONObject req = new JSONObject();
try {
req.put("success", response.getBoolean("success"));
req.put("challenge_id", response.getInt("challenge_id"));
req.put("challenge", response.getString("challenge"));
req.put("sending_method", sendingMethod);
req.put("sending_destination", sendingDestination);
} catch (Exception e) {
callback.onError(e.toString());
}
callback.onSuccess(req);
}
});
}
// Inside your app, use a button onClick that calls
// openPinVerification to start the flow
public void openPinVerification(View view) {
Cotter.PinVerification.startFlow(view, Dashboard.class, "LOGIN");
}
Reset PIN functionality is an update that is available starting from version
0.4.5
Last modified 2yr ago