# JS Button

The ID Check Javascript Button is the easiest way to implement ID Check on your website. The button provides a seamless user experience, taking the user through the ID Check process on their phone and notifying your page when the process is complete.

# Integration Summary

# Starting ID Checks

You can fully integrate the JS Button into your system in a matter of minutes by following these simple steps.

  1. Include the source code on your site
  2. Initialize the button with your public key
  3. Set up the idCheckCreated event handler
  4. Set up the idCheckComplete event handler
  5. Mount the button in your DOM
  6. Start the ID Check

That's it! The ID Check results are now available via your Caisson Dashboard, or programmatically with just a bit more work.

# Fetching ID Check Results

Once the ID Check is complete, you'll be able to fetch the data via your servers. Remember, ID Checks are personal information, so treat this data with care.

  1. Upgrade the Exchange Token returned when an ID Check is started
  2. Fetch ID Check Results using the key obtained from the previous step

# Detailed Integration Guide

# Starting ID Checks

# 1. Include the source code

To get started, simply include caisson.js in the head of your HTML document:

<script src="https://api.caisson.com/v1/caisson.js"></script>

Then, create a <div> in your page’s body where the ID Check button will be mounted:

<div id="caisson-button"></div>

# 2. Initialize the button

First, we'll use Caisson("your_public_api_key") to initialize the library. Once initialized, we configure the ID Check button and mount it onto your page.

TIP

You can find your API keys in the developer page.

    // Initialize Caisson with your public API key
    var caisson = Caisson("{{your_caisson_public_key}}");
    var button = caisson.button(
            {
                customer_id: "1234",  //how your systems identify the customer.
                appearance: "dark"
            });

# 3. Set up idCheckCreated Handler

    button.on("idCheckCreated", function(idCheck){
        //make sure to save the idCheck info
        //so you can use it once the Check is complete.

        window.myIDCheck = idCheck
        fetch("/my/exchange/path", {
            method: "POST",
            headers: {
                "Content-Type": "application/json"
            },
            body: JSON.stringify(
            {
                cust_id: idCheck.customer_id,
                exchange_token: idCheck.check_exchange_token
            })
        })
    });

# 4. Set up idCheckComplete Handler

    button.on("idCheckComplete", function(){

        //the completed event doesn't have a payload,
        //so you'll need to re-use the data that came
        //from the created event.
        var idCheck = window.myIDCheck
        fetch("/my/checkcomplete/path", {
            method: "POST",
            headers: {
                "Content-Type": "application/json"
            },
            body: JSON.stringify(
            {
                cust_id: idCheck.customer_id,
                exchange_token: idCheck.check_exchange_token
            })
        })        
    });

# 5. Mount the Button

    // Mount the button element using a css selector (usually a <div>)
    button.mount("#caisson-button");

# 6. Start the ID Check

The button is now on the page. You can start the ID Check flow by clicking on it.

TIP

Remember, the ID Check flow can only be entered from a mobile browser, but we got you covered. The button will detect your customer's environment and instruct them accordingly.

# Mobile

On your mobile browser, the button will automatically start the ID Check flow. Screenshot of Mobile Button

# Desktop

On the desktop, you will see the Handoff Dialog. This dialog offers two ways to direct your customer to their mobile phone: they can scan the QR code with your phone's camera or simply enter your phone number to receive a link to the flow. Screenshot of Handoff

If you want to see a full working demo, you can find one at demo.caisson.com. Checkout the source code on github: id-check-example.

# Fetching ID Check Results

# 1. Upgrade the Exchange Token

When an ID Check is started, the idCheckCreated event fires, returning a check_exchange_token. Create an endpoint on your server that allows you to hand this token back to your backend. Be careful not to use query parameters! While this token can't be used to directly access ID Check results, it should be treated as private information. The route to this endpoint is set in the event handler for idCheckCreated, and as illustrated there, you'll POST the check_exchange_token and the customer_id (defined by you) back to your servers for further proccessing.

Once your server side has both the check_exchange_token and the customer_id, you'll use the Caisson exchangetoken route to exchange it for the Caisson check_id needed to fetch results in the next step. Be sure to associate this check_id with your customer's record (probably via the customer_id you've handed to Caisson for this ID Check request).

# 2. Fetch ID Check Results

The API to fetch results requires both your secret API key and the check_id you obtained throug the exchange process above. Due to the private nature of both of these pieces of information, you should NOT try to fetch the results from your customers' browsers. Rather, request the data from your servers. The data returned from an ID Check is sensitive, and should be handled with the utmost care and security. Fetching the ID Check results is straightforward, and details can be found here. All you'll need to do is set the appropriate HTTP headers and issue a GET request to the /idcheck enpoint. Caisson returns a minimal amount of data by default, but you can request all the fields you need via the fields query parameter.

# Show your colors

The look and feel of the entire flow can be customized to provide a seamless user experience. Go to the settings page where you’ll be able to easily edit the appearance of the ID Check flow.

Screenshot of Handoff