Transaction Quick Start: Android

The BindID service is an app-less, strong portable authenticator offered by Transmit Security. BindID uses FIDO-based biometrics for secure, convenient, and consistent passwordless authentication. This guide explains how to integrate BindID into your Android application to authenticate financial transactions (using transaction signing per PSD2.0 SCA).Learn more about BindID

Before You Start

This guide assumes that you've already set up your Android application to authenticate user login with BindID (see Android Login Quick Start), including the following:

  • BindID Android SDK was added to your project
  • BindID Android SDK was configured with the client ID and to work with sandbox
  • App manifest was updated to support deep linking for the redirect URI
  • Application was configured in the BindID Admin Portal with the redirect URI
  • New users are directly authenticated and registered (alias is set)

Step 1: Get Your Credentials

To integrate with BindID, you'll need your client credentials to identify your Android application in requests to the BindID service. From Applications in the BindID Admin Portal, obtain your client ID from the Application you created.

Note: This guide assumes that the redirect URI you plan to use to return to the mobile application after successful authentication has already been configured when configuring the Application for a login flow.

Step 2: Request Transaction Signing

Your payment screen should initiate a transaction signing request (e.g., upon clicking a payment button). The request should include transaction details to display to the user to approve before authenticating. The transaction details are encrypted by default.

You can initiate the request by including a snippet like the one below in your payment screen, after substituting the tokens. This code will be used to authenticate the user, retrieve the user tokens using the authorization code (PKCE flow), and send the tokens to your backend. This example shows a client-side PKCE token exchange, however, BindID also supports a backend PKCE token exchange using the Token API.

fun transaction() {
XmBindIdSdk.getInstance().signTransaction(
XmBindIdTransactionSigningRequest.create(
"[REDIRECT_URI]",
XmBindIdTransactionSigningData.create(
XmBindIdTransactionSigningDisplayData.create(
"[PAYEE]",
"[PAYMENT_AMOUNT]",
"[PAYMENT_METHOD]"
)
)
).apply {
usePkce = true
}
)
.addListener(object : ObservableFuture.Listener<XmBindIdResponse, XmBindIdError> {
override fun onComplete(response: XmBindIdResponse) {
Log.i("BID", "transaction successful")
exchange(response)
}
override fun onReject(error: XmBindIdError) {
handleError(error)
}
})
}
TokenSubstitute with...
[REDIRECT_URI]Redirect URI that returns to the mobile application upon successful authentication with the authentication result. This URI must be configured in your Application, and your app manifest.
[PAYEE]Requested payment recipient. Cannot be more than 40 characters long.
[PAYMENT_AMOUNT]Requested payment amount, including the currency symbol or code (e.g., $100.99). Cannot be more than 15 characters long.
[PAYMENT_METHOD]Requested payment method. Cannot be more than 40 characters long.

Note: The snippet above assumes that the exchange and handleError functions were implemented, as described in the Android Login Quick Start.

Step 3: Validate User Token

The ID token received in step 2 contains various user information as claims, including claims that allow you to validate that the transaction signing was successfully completed.

  • The bindid_psd2_transaction claim contains transaction details that were displayed to the user (see example below). The user is required to approve these details before they authenticate. You should validate that payee, payment_method, and payment_amount match the corresponding parameters that you passed in the transaction signing request (in step 2). For example:

    {
    ...
    "bindid_psd2_transaction": {
    "display_data": {
    "payee": "Acme",
    "payment_amount": "$100.99",
    "payment_method": "Acme Card"
    }
    }
    ...
    }
  • The amr claim provides information about the authenticator used to authenticate. Since PSD2.0 SCA requires multi-factor authentication, validate that the array of AMR values includes ts.bind_id.mfca which indicate that a multi-factor authenticator was used. For example:

    {
    ...
    "amr": ["ts.bind_id.ama", "ts.bind_id.mfca"],
    ...
    }

Step 4: Test Your Integration

Once you complete your integration with BindID, test your integration as described below. Note that this assumes the user is already registered to BindID, and the device has the Chrome browser installed (to support FIDO2 biometric authentication).

  1. From your app payment screen, initiate the transaction signing request (passing the transaction details to display to the user).
  2. An approval screen is displayed with your logo, along with the transaction details passed in the payment request (e.g., payment amount). Click to Approve.
  3. Run the biometric authentication process on your mobile device.
  4. The BindID process ends and returns to your application.
  5. Validate the user token (as described in step 3), including the transaction details displayed to the user and the authenticator used.