Android integration guide
Scan a payment card for fraud protection with CardVerify Check for Android.

Requirements

    Android API level 21 or higher
    AndroidX compatibility
    Kotlin coroutine compatibility
Note: Your app does not have to be written in kotlin to integrate this library, but must be able to depend on kotlin functionality.

SDK Size

We try to keep our SDK as small as possible while maintaining good performance. The size impact including our SDK into your app varies depending on some features of your app:
We also provide custom implementations of the TensorFlow Lite library that are stripped-down to only support the functions our SDK uses. These custom implementations can drastically reduce the size of the SDK overall.
TF Flavor
Size (not bundled)
Size (bundled)
Dependency
TensorFlow official release
4.00MB
1.00MB
org.tensorflow:tensorflow-lite:2.4.0
Bouncer TF all architectures
2.12MB
0.62MB
com.getbouncer:tensorflow-lite:2.1.0004
Bouncer TF arm only
1.06MB
0.62MB
com.getbouncer:tensorflow-lite-arm-only:2.1.0004
There are two variants of our ML models that you can choose to include in your application; the larger size, faster performing and smaller size, slower performing models. If selecting the slower performing models, the SDK will still attempt to download the faster models over the internet once your app has launched. This helps reduce the size of your app while still guaranteeing performance.
Flavor
Size (not bundled)
Size (bundled)
Dependency
full size
2.9 MB
2.7 MB
com.getbouncer:scan-payment-full:2.1.0004
minimal
1.6 MB
1.2 MB
com.getbouncer:scan-payment-minimal:2.1.0004
download only
0.0 MB
0.0 MB
no dependency required
Given the above table, select the framework you'll be using to calculate the impact that the bouncer SDK will have on the size of your application:
Using download only models
Base SDK
TFLite Framework
Total
App supports all architectures and not bundled
1.0 MB
2.1 MB
3.1 MB
App supports ARM only and not bundled
1.0 MB
1.1 MB
2.1 MB
App released as bundle
1.0 MB
0.6 MB
1.6 MB
App already uses TFLite
1.0 MB
0.0 MB
1.0 MB
Using minimal models
Base SDK
TFLite Framework
Total
App supports all architectures and not bundled
2.99 MB
2.12 MB
5.11 MB
App supports ARM only and not bundled
2.99 MB
1.06 MB
4.05 MB
App already uses TFLite and not bundled
2.99 MB
0.0 MB
2.99 MB
App released as bundle
2.04 MB
0.62 MB
2.66 MB
App already uses TFLite and bundled
2.04 MB
0.0 MB
2.04 MB
Using full size models
Base SDK
TFLite Framework
Total
App supports all architectures and not bundled
3.9 MB
2.1 MB
6.0 MB
App supports ARM only and not bundled
3.9 MB
1.1 MB
5.0 MB
App released as bundle
3.9 MB
0.6 MB
4.5 MB
App already uses TFLite
3.9 MB
0.0 MB
3.9 MB
Bouncer provides a method Scan.isDeviceArchitectureArm() which will return true if the device is running an ARM architecture. This can be used to determine if the device supports scanning when the -arm-only TFLite framework is in use.

Integration

1
dependencies {
2
implementation 'com.getbouncer:cardverify-ui:2.1.0004'
3
4
// you must select one of the following tensorflow-lite libraries. See the
5
// above chart to understand how each will affect the size of your app.
6
7
// If you're already using tensorflow lite elsewhere in your project, make
8
// sure you depend on the TFLite framework.
9
implementation 'org.tensorflow:tensorflow-lite:2.4.0'
10
11
// If you need to support both ARM and x86 devices (< 1% of all android
12
// devices), include this dependency.
13
implementation 'com.getbouncer:tensorflow-lite:2.1.0004'
14
15
// If you only plan to support ARM devices, use this library
16
implementation 'com.getbouncer:tensorflow-lite-arm-only:2.1.0004'
17
}
Copied!
If you are already using CardScan, leave that dependency in place.
By default, all of the ML models used to scan are downloaded during the call to CardScanActivity.warmUp. However, if you're concerned about scanning in areas with poor network connectivity, you may also want to include default versions of the scanning ML models in your app. Doing so will guarantee that scan will be available regardless of download speed or network connectivity.
There are two options for including ML models by default into your app: 1. minimal models 2. full models
See the charts above to determine how each of these dependencies will impact the size of your app.

Full Models

The full models are the same as those downloaded over the network. By adding this dependency to your app, you can ensure the maximum performance of the SDK regardless of network connection, but at the cost of a larger SDK.
1
dependencies {
2
implementation "com.getbouncer:scan-payment-full:2.1.0004"
3
}
Copied!

Minimal Models

The minimal models perform slightly slower than the full ML models. The SDK will attempt to download the full versions of the models during CardScanActivity.warmUp, which will override the minimal models. However, in the event the download takes too long or fails, the minimal ML models ensure that the scan will still function with only a small impact to performance.
1
dependencies {
2
implementation "com.getbouncer:scan-payment-minimal:2.1.0004"
3
}
Copied!

Alternative camera implementations

By default, bouncer uses the Android Camera 1 API. To use Camera2 or CameraX, add one of the following imports:
1
implementation "com.getbouncer:scan-camerax:2.1.0004"
2
3
// OR
4
5
implementation "com.getbouncer:scan-camera2:2.1.0004"
Copied!

Types of verification

The library provides three forms of verification:
    Network
    Local
    ZeroFraud

Network verification

This is the standard way of verifying payment cards. It involves integration with Bouncer servers to run the most complete set of validation logic on the results from the scan.
To use network verification, use the com.getbouncer.cardverify.ui.network packages to launch the verification flow.
Important note: At no point does any sensitive information (e.g. card number) leave the device.

Local verification

This is a less stringent verification flow than network verification, as the verification logic runs locally on the device. In cases where it is not viable to send a payload to Bouncer servers, this can be used to verify the authenticity of a card, but will be less accurate than network verification.
To use local verification, use the com.getbouncer.cardverify.ui.local packages to launch the verification flow.

ZeroFraud verification

This flow is designed for verifying the authenticity of cards when adding them to a platform. It is the same as network verification, but does not return an encrypted payload from the scan. Instead, the payload is automatically uploaded to bouncer servers, where the result of the card add scan can be referenced later, for example during a transaction attempt.
To use zerofraud verification, use the com.getbouncer.cardverify.ui.zerofraud packages to launch the verification flow.

Using

This library provides a user interface through which payment cards can be verified. API keys can be created through the Bouncer API console. Please contact support to ensure the correct permissions have been added to your API key.

1. Library warm up

CardVerify will download ML models for use in verifying the authenticity of payment cards. To ensure these models are downloaded by the time CardVerify runs, please make sure to call the warmUp method on CardVerify as early in the app flow as possible. In most cases, this can be done in the onApplicationCreate method of your app. Note that warmUp processes on a background thread and will not affect your app's startup time.

Adding an application lifecycle listener

If your app doesn't already listen to application lifecycle events, you can extend the Application object and connect it using your manifest by setting android:name on your application node:
1
<application
2
android:icon="..."
3
android:label="..."
4
android:roundIcon="..."
5
android:name=".MyApplication">
6
7
...
8
9
</application>
Copied!
Create a class with the same name:
Kotlin
Java
1
const val API_KEY = "<your_api_key_here>";
2
3
class MyApplication : Application() {
4
5
override fun onCreate() {
6
super.onCreate();
7
8
/*
9
* CardScan will attempt to update the ML models used to scan payment
10
* cards. By placing the call to the `warmUp` method in the
11
* `onApplicationCreate` method of your app, you allow the most time
12
* possible for models to upgrade. Note that `warmUp` processes on a
13
* background thread and will not affect your app's startup time.
14
*
15
* Note: the last parameter, `initializeNameAndExpiryExtraction`,
16
* determines if name and expiry extraction (beta feature) should be
17
* turned on.
18
*/
19
CardVerifyActivity.warmUp(this, API_KEY, initializeNameAndExpiryExtraction = false)
20
}
21
}
Copied!
1
public class MyApplication extends Application {
2
public static final String API_KEY = "<your_api_key_here>";
3
4
@Override
5
public void onCreate() {
6
super.onCreate();
7
8
/*
9
* CardScan will attempt to update the ML models used to scan payment
10
* cards. By placing the call to the `warmUp` method in the
11
* `onApplicationCreate` method of your app, you allow the most time
12
* possible for models to upgrade. Note that `warmUp` processes on a
13
* background thread and will not affect your app's startup time.
14
*
15
* Note: the last parameter, `false`, determines if name and expiry
16
* extraction (beta feature) should be turned on.
17
*/
18
CardVerifyActivity.warmUp(this, API_KEY, false);
19
}
20
}
Copied!

2. Starting the flow

To start the flow, CardVerifyActivity provides a start method which takes the required parameters and launches the flow. Pass in the payment card details that you want to verify, including the IIN (first six digits) and last four digits of the payment card.
Kotlin
Java
1
class LaunchActivity : Activity, CardVerifyActivityResultHandler {
2
3
override fun onCreate(savedInstanceState: Bundle?) {
4
super.onCreate(savedInstanceState)
5
setContentView(R.layout.activity_launch)
6
7
findViewById(R.id.scanCardButton).setOnClickListener { _ ->
8
CardVerifyActivity.start(
9
activity = LaunchActivity.this,
10
apiKey = MyApplication.API_KEY,
11
iin = requiredCardNumber.take(6),
12
lastFour = requiredCardNumber.takeLast(4)
13
)
14
}
15
}
16
17
override fun onActivityResult(
18
requestCode: Int,
19
resultCode: Int,
20
data: Intent
21
) {
22
super.onActivityResult(requestCode, resultCode, data)
23
24
if (CardVerifyActivity.isVerifyResult(requestCode)) {
25
CardVerifyActivity.parseVerifyResult(resultCode, data, this)
26
}
27
}
28
29
override fun cardScanned(
30
instanceId: String?,
31
scanId: String?,
32
scanResult: ScanResult,
33
payloadVersion: Int,
34
encryptedPayload: String
35
) {
36
/*
37
* The user scanned a card. Details of the card are in the `scanResult`
38
* variable. Send the value in the `encryptedPayload` variable to
39
* Bouncer servers to check if the card is genuine. See the server
40
* integration documentation for details.
41
*/
42
}
43
44
override fun userMissingCard(scanId: String?) {
45
// The user does not have possession of this card
46
}
47
48
override fun enterManually(scanId: String?) {
49
// The user wants to manually enter a card
50
}
51
52
override fun userCanceled(scanId: String?) {
53
// The user canceled the scan.
54
}
55
56
override fun cameraError(scanId: String?) {
57
// The scan failed because of a camera error.
58
}
59
60
override fun analyzerFailure(scanId: String?) {
61
// The scan failed to analyze images from the camera.
62
}
63
64
override fun canceledUnknown(scanId: String?) {
65
// The scan was canceled due to unknown reasons.
66
}
67
}
Copied!
1
class LaunchActivity
2
extends AppCompatActivity
3
implements CardVerifyActivityResultHandler {
4
5
private static final String API_KEY = "<your_api_key_here>";
6
7
@Override
8
protected void onCreate(@Nullable Bundle savedInstanceState) {
9
super.onCreate(savedInstanceState);
10
setContentView(R.layout.activity_launch);
11
12
findViewById(R.id.scanCardButton).setOnClickListener(v ->
13
CardVerifyActivity.start(
14
activity = LaunchActivity.this,
15
apiKey = MyApplication.API_KEY,
16
iin = requiredCardNumber.take(6),
17
lastFour = requiredCardNumber.takeLast(4)
18
)
19
);
20
}
21
22
@Override
23
protected void onActivityResult(
24
int requestCode,
25
int resultCode,
26
@Nullable Intent data
27
) {
28
super.onActivityResult(requestCode, resultCode, data);
29
30
if (CardVerifyActivity.isVerifyResult(requestCode)) {
31
CardVerifyActivity.parseVerifyResult(resultCode, data, this);
32
}
33
}
34
35
@Override
36
public void cardScanned(
37
@Nullable String instanceId,
38
@Nullable String scanId,
39
@NotNull ScanResult scanResult,
40
int payloadVersion,
41
@NotNull String encryptedPayload
42
) {
43
/*
44
* The user scanned a card. Details of the card are in the `scanResult`
45
* variable. Send the value in the `encryptedPayload` variable to
46
* Bouncer servers to check if the card is genuine. See the server
47
* integration documentation for details.
48
*/
49
}
50
51
@Override
52
public void userMissingCard(@Nullable String scanId) {
53
// The user does not have possession of this card
54
}
55
56
@Override
57
public void enterManually(@Nullable String scanId) {
58
// The user wants to manually enter a card
59
}
60
61
@Override
62
public void userCanceled(@Nullable String scanId) {
63
// the user canceled the scan
64
}
65
66
@Override
67
public void cameraError(@Nullable String scanId) {
68
// scan was canceled due to a camera error
69
}
70
71
@Override
72
public void analyzerFailure(@Nullable String scanId) {
73
// scan was canceled due to a failure to analyze camera images
74
}
75
76
@Override
77
public void canceledUnknown(@Nullable String scanId) {
78
// scan was canceled for an unknown reason
79
}
80
}
Copied!
CardVerify will return an encrypted payload containing information about the payment card the user scanned. As in the example above, you can receive this payload using your activity or fragment's onActivityResult method.

Name and Expiry Extraction

Name and expiry extraction are in beta, and must be manually enabled. The following steps enable them:
    1.
    In the warmUp method, set the optional initializeNameAndExpiryExtraction parameter to true.
    2.
    In the start method, set the optional enableNameExtraction and/or enableExpiryExtraction parameters to true.
The scanner will now attempt to extract the cardholder name and card expiry during scan, and will return the values in the cardScanned method.
To fine-tune the number of images that name and expiry extraction use, see the advanced customization documentation.

Model Downloading

By default, the SDK will download updates to ML models used to extract card information. To disable model downloading, set the following flag to false before calling warmup or starting the scan:
Kotlin
Java
1
com.getbouncer.scan.framework.Config.downloadModels = false
Copied!
1
com.getbouncer.scan.framework.Config.setDownloadModels(false);
Copied!

UI Customizing

CardVerify is built to be customized to fit your UI.

Basic modifications

To modify text, colors, or padding of the default UI, see the customization documentation.

Extensive modifications

To modify arrangement or UI functionality, CardVerify can be used as a library for your custom implementation. See the example single-activity demo app.

Developing

See the development docs for details on developing for CardVerify.

License

A licensing agreement is required to use this library.
All contributors must agree to the CLA.
Last modified 3mo ago