Transaction Quick Start: Web

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 web application to authenticate financial transactions (using transaction signing per PSD2.0 SCA). This guide assumes that your web application uses BindID to authenticate user login, so users would already be registered before their first transaction. Learn more about BindID

Step 1: Configure Your Application

To integrate with BindID, you'll need to configure an application in the BindID Admin Portal (see Admin Portal: Get Started). You can either create a new application or use one that you already created.

From Applications, here is the basic client setup that is required for your application:

Set the allowed redirect URIs—Specify the list of pages to which users are allowed to be redirected after authentication.
Get your BindID credentials—Obtain the client ID and client secret used to identify your web application to the BindID Service.

Step 2: Configure SDK in Payment Page

Your page can access all the BindID functionality by loading the BindID SDK. Add the code used to load the BindID SDK to your front-end web application, by including the following HTML tags:

<script src="https://polyfill.io/v3/polyfill.min.js?features=Promise%2CPromise.prototype.finally%2CTextDecoder%2CTextEncoder%2CObject.entries"></script>
<script src="https://signin.bindid-sandbox.io/bindid-sdk/transmit-bind-id-sdk.js" defer></script>

You also need to configure the BindID SDK programmatically with the client ID from step 1. To do this, invoke the initialize() SDK method (see the API reference). For example:

function initializeSDK() {
    window.XmBindId.initialize({
        clientId: '[CLIENT_ID]',
        apiCompat: window.XmBindId.XmBindIdApiCompatibilityLevel.UseLatest
    }).then(res => {
        alert('SDK Initialized');
    });
}

where [CLIENT_ID] should be replaced with your client ID.

Step 3: Request Transaction Signing

Your payment page should initiate a transaction signing request (e.g., upon clicking a payment button). The request should include transaction details that will be displayed to the user so they can approve them 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 page, after substituting the tokens described below.

function invokeBindId() {
    window.XmBindId.signTransaction({
        redirectUri: '[REDIRECT_URI]',
        customMessage: 'Approve Payment',
        transactionSigningData: {
            displayData: {
                payee: '[PAYEE]',
                paymentAmount: '[PAYMENT_AMOUNT]',
                paymentMethod: '[PAYMENT_METHOD]'
            },
            essential: true
        }
    }).then(res => {
        onSuccess(res);
    }, err => {
        onFailure(err);
    })
}

Token	Substitute with...
`[REDIRECT_URI]`	Redirect URI set in step 1.
`[PAYEE]`	Requested payment recipient.
`[PAYMENT_AMOUNT]`	Requested payment amount, including the currency symbol or code (e.g., $100.99).
`[PAYMENT_METHOD]`	Requested payment method.

Step 4: Create Redirect Page

Upon completing authentication, BindID redirects to the Redirect URI provided in step 1. The URL encodes the BindID authentication result. Your application should respond to this URL by serving a web page that uses the BindID SDK to extract and process the authentication result.

This redirect page should load and initialize the BindID SDK, as described in Step 2.

Next, the page should use the BindID SDK to process the authentication result. For example:

<body>
 …
 <script>
   function sendAuthCodeToServer(authCode) {
    // Add code to send the authCode to your application server here
   }
   function handleError(err) {
    // Add code to process the authentication error here
   }
   window.XmBindId.processRedirectResponse()
    .then(res => { sendAuthCodeToServer(res.code); },
        err => { handleError(err); })
 </script>
 …
</body>

The functions in the snippet above should be implemented as follows:

sendAuthCodeToServer should send the authorization code received upon successful authentication to your server, where it will be processed to retrieve user info (see step 5).
handleError should respond to an authentication error, possibly by presenting a suitable message to the user.

Step 5: Get User Token

To retrieve user information, the authorization code that was sent to your application server in step 4 should now be sent to the BindID service using a backend API, along with the client secret obtained in step 1. The authorization code will be exchanged for a user token.

Send the following HTTP POST request, after substituting the tokens as described below:

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: signin.bindid-sandbox.io

grant_type=authorization_code&code=[AUTH_CODE]&redirect_uri=[REDIRECT_URI]&client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]

Token	Substitute with...
`[AUTH_CODE]`	Authorization code received from the client in step 4.
`[CLIENT_ID]`	Client ID obtained in step 1.
`[CLIENT_SECRET]`	Client Secret obtained in step 1.
`[REDIRECT_URI]`	Redirect URI set in step 1.

The response to this request will include a JWT token encoding the user information:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": [ACCESS_TOKEN],
  "token_type": "Bearer",
  "expires_in": [EXPIRATION_TIME],
  "id_token": [ID_TOKEN]
}

Token	Description
`[ACCESS_TOKEN]`	Access token.
`[EXPIRATION_TIME]`	Time in seconds until the access token expires.
`[ID_TOKEN]`	JWT encoding identifying info and other info about the authenticating user.

Step 6: Validate User Token

The ID token ([ID_TOKEN]) received in step 5 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 3).
{
...
"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 indicates that a multi-factor biometric authenticator was used. For example:
{
...
"amr": ["ts.bind_id.ama", "ts.bind_id.mfca"],
...
}

Step 7: 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 registered a desktop biometric authenticator:

Run the payment webpage and initiate the transaction signing request (passing the transaction details to display to the user).
The page should redirect to the BindID Sandbox environment.
You should see your logo as part of the page, along with "Approve Payment" in the title.
Approve the information on the desktop device, which should display the transaction details passed in the payment request (e.g., payment amount).
Run the biometric authentication process on the desktop device.
The BindID process ends and returns to your application.
Obtain the user token as described in step 5
Validate the user token (as described in step 6), including the transaction details displayed to the user and the authenticator used.

Transaction Quick Start: Web#

Step 1: Configure Your Application#

Step 2: Configure SDK in Payment Page#

Step 3: Request Transaction Signing#

Step 4: Create Redirect Page#

Step 5: Get User Token#

Step 6: Validate User Token#

Step 7: Test Your Integration#