Product Guide

Javascript Example

Suggest Edits

Authentication

For security reasons, you will first have to allowlist the URL of the website or web app on which the embedded flows will be hosted. This can be done from the 'Settings' tab on dashboard.aiprise.com under 'IFrame Origin Allowlist'.

Please note that if the source is not authorized, an error message saying Unable to create session. Please try again. will appear. To identify the precise hostname that needs to be allowlisted, you can examine the console.

Install the AiPrise Web SDK

Start by adding this script tag to the page where you need to perform the KYC:

<script src="https://cdn.aiprise.com/js/v1/web-sdk.min.js"></script>

Option 1: Web Button

This will integrate our verification button into your app. On clicking it, a modal will be launched where the user data will be collected. The mode and template-id are the only required attributes. You can add others as per your requirements.

Basic Usage

Just add the <aiprise-button /> tag in your page wherever you want to place it:

<aiprise-button 
  mode="SANDBOX/PRODUCTION"
  template-id="YOUR_TEMPLATE_ID"
/>

Advanced Usage

Apart from mode and template-id, there are a few more props that you can pass. These props allow you to change things like the button text, color, logo image, etc. All of them are listed in the example below.

In addition to the props, there are also five events fired by the button which you can listen to:
(i) started: Will be fired after the session starts. i.e. when the user clicks on the button, the modal opens and a new session gets created (event will be fired after after the loading screen is completed).
(ii) abandoned: Will be fired when the user quits out of the verification flow by clicking the close button and confirming that they want to stop the verification.
(iii) successful: This will be fired when the user completes filing out the entire verification form and reaches the last page. They may not have clicked the close button yet so the modal is still visibile at this point but no other information has to be collected from them. Note: "successful" does not mean that the KYC is approved. It just means form is successfully filled by the user.
(iv) continue: This will be fired AFTER the user clicks the close or continue button on the last page. The SDK will handle closing of the modal automatically in that case so no action is required on your end. The event is just in case you want to perform any task in your application after this point.
(v) error: This event is fired in case the session creation filed. This can happen for a number of reasons like invalid template ID, using the SDK outside your allowlisted hosts, etc. You can check the error message in the console to see why it's happening.

<!-- user-data and additional-info inside aiprise-button are OPTIONAL -->
<aiprise-button
  id="my-verification-button"
  template-id="YOUR_TEMPLATE_ID"
  mode="SANDBOX/PRODUCTION"

  callback-url="http://yourcallbackurl.com"
  events-callback-url="http://yourcallbackurl.com"

  client-reference-id="SOME_ID_YOU_WANT_TO_ASSOCIATE_WITH_YOUR_REQUEST"
  client-reference-data='{ "some_data": "some_value" }'

  ui-options='{ 
    "id_verification_module": {
      "allowed_country_code": "US" // 2-Letter Country Code. Disables all other countries.
    }
  }'
  verification-options='{
    "AML_CONFIG": {
      "fuzziness_score": 0.8, // Number
      "exact_match": 0.8, // Number
      "monitoring": false // Boolean
    }
  }'

  user-data='{ // Optional / Only for KYC
    "first_name": "Your Users First Name",
    "middle_name": "Your Users Middle Name",
    "last_name": "Your Users Last Name",
    "date_of_birth": "YYYY-MM-DD",
    "phone_number": "+11234567890",
    "email_address": "[email protected]",
    "ip_address": "0.0.0.0",
    "address": {
      "address_street_1": "...",
      "address_street_2": "...",
      "address_city": "...",
      "address_state": "...",
      "address_zip_code": "...",
      "address_country": "..."
    }
  }'
  additional-info='[ // Optional / Only for KYC
    {
      "additional_info_type": "TYPE_HERE",
      "additional_info_data": "DATA_HERE",
    },
    {
      "additional_info_type": "TYPE_2_HERE",
      "additional_info_data": "DATA_2_HERE",
     },
  ]'

  icon="YOUR_40X40_LOGO_URL"
  title="YOUR_BUTTON_TEXT"
  color="YOUR_BRAND_HEX_CODE_WITH_#"
  text-color="BUTTON_TEXT_COLOR_HEX_CODE_WITH_#"
  theme="[THEME_OPTIONS_HERE]"
 
/>

<!-- Listen for Events -->
<script>
  var verifyButton = document.getElementById("my-verification-button");

  // Started Event
  verifyButton.addEventListener("aiprise:started", function (e) {
    console.log("Session started with ID: " + e.detail.verification_session_id);
  });

  // Business Profile Created (KYB Only)
  verifyButton.addEventListener("aiprise:business-profile", function (e) {
    console.log("Business profile created with ID: " + e.detail.business_profile_id);
  });
  
  // Abandoned Event
  verifyButton.addEventListener("aiprise:abandoned", function (e) {
    console.log("Session with ID " + e.detail.verification_session_id + " was abandoned.");
  });

  // Successful Event
  verifyButton.addEventListener("aiprise:successful", function (e) {
    console.log("Session with ID " + e.detail.verification_session_id + " was successful.");
  });

  // Continue Event
  verifyButton.addEventListener("aiprise:continue", function (e) {
    console.log("Session with ID " + e.detail.verification_session_id + " was continued.");
  });

  // Error Event
  verifyButton.addEventListener("aiprise:error", function (e) {
    console.log("Error " + e.detail.error_code);
    // Error Codes:
    // SESSION_FAILED is fired when session creation fails (due to incorrect values, internet or server issues, etc)
    // SESSION_EXPIRED happens when you try to resume a session but the session ID has expired
    // SESSION_COMPLETED happens when you try to resume a session but the session has already been completed by the user
  });
</script>

Styling

In your stylesheet, just write the button's class name and add the CSS properties you want to apply:

.aiprise-button {
    margin-top: 16px;
    margin-left: 16px;
    /* Other CSS stuff... */
}

Note: Avoid adding CSS properties to the inner elements of the button like the icon or the title div. These can change in future versions of the SDK. Only add CSS to the root button element using the aiprise-button class.

To customize the verification UI you can pass in the theme options which are documented here.

Option 2: Web Frame

This option allows you to integrate the verification flow directly into your website or app using an iframe. You can do your styling in a div that surrounds the iframe. Here, you take the responsibility or showing the verification flow (after some user action like a button click) and hiding it when the user has filled the entire form.

Just like the button, the mode and template-id are the only required attributes. You can add others as per your needs.

Basic Usage

<div style="width: 400px; height: 850px;">
  <aiprise-frame
    mode="SANDBOX/PRODUCTION"
    template-id="YOUR_TEMPLATE_ID"
  />
</div>

Advanced Usage

Similar to the button component, you can pass props here for the callback URL, user data, etc. Full list of attributes are visible in the example below.

Also similar to the button, there are events that you can listen to: started, successful, continue, error.
Note: There is no abandoned event here unlike the button since iframe's cant be abandoned. It's always visible till the host application i.e. your website or app hides it.

<!-- user-data and additional-info inside aiprise-frame are OPTIONAL -->
<div style="width: 400px; height: 850px">
  <aiprise-frame
    id="my-verification-frame"
    template-id="YOUR_TEMPLATE_ID"
    mode="SANDBOX/PRODUCTION"

    callback-url="http://yourcallbackurl.com"
    events-callback-url="http://yourcallbackurl.com"

    client-reference-id="SOME_ID_YOU_WANT_TO_ASSOCIATE_WITH_YOUR_REQUEST"
    client-reference-data='{ "some_data": "some_value" }'

    ui-options='{ 
      "id_verification_module": {
        "allowed_country_code": "US" // 2-Letter Country Code. Disables all other countries.
      }
    }'
    verification-options='{
      "AML_CONFIG": {
        "fuzziness_score": 0.8, // Number
        "exact_match": 0.8, // Number
        "monitoring": false // Boolean
      }
    }'

    user-data='{ // Optional / Only for KYC
      "first_name": "Your Users First Name",
      "middle_name": "Your Users Middle Name",
      "last_name": "Your Users Last Name",
      "date_of_birth": "YYYY-MM-DD",
      "phone_number": "+11234567890",
      "email_address": "[email protected]",
      "ip_address": "0.0.0.0",
      "address": {
        "address_street_1": "...",
        "address_street_2": "...",
        "address_city": "...",
        "address_state": "...",
        "address_zip_code": "...",
        "address_country": "..."
      }
    }'
    additional-info='[ // Optional / Only for KYC
      {
        "additional_info_type": "TYPE_HERE",
        "additional_info_data": "DATA_HERE",
      },
      {
        "additional_info_type": "TYPE_2_HERE",
        "additional_info_data": "DATA_2_HERE",
       },
    ]'

    icon="YOUR_40X40_LOGO_URL_FOR_ERROR_SCREEN"
    theme="[THEME_OPTIONS_HERE]"
  />
</div>

<!-- Listen for Events -->
<script>
  var verifyFrame = document.getElementById("my-verification-frame");
  
  // Started Event
  verifyFrame.addEventListener("aiprise:started", function (e) {
    console.log("Session started with ID: " + e.detail.verification_session_id);
  });

  // Business Profile Created (KYB Only)
  verifyButton.addEventListener("aiprise:business-profile", function (e) {
    console.log("Business profile created with ID: " + e.detail.business_profile_id);
  });

  // Successful Event
  verifyFrame.addEventListener("aiprise:successful", function (e) {
    console.log("Session with ID " + e.detail.verification_session_id + " was successful.");
    // NOTE: "Sucessful" does not mean the KYC is approved. It just means form has been filled.
  });

  // Continue Event
  verifyFrame.addEventListener("aiprise:continue", function (e) {
    console.log("Session with ID " + e.detail.verification_session_id + " was continued.");
  });

  // Error Event
  verifyFrame.addEventListener("aiprise:error", function (e) {
    console.log("Error " + e.detail.error_code);
    // Error Codes:
    // SESSION_FAILED is fired when session creation fails (due to incorrect values, internet or server issues, etc)
    // SESSION_EXPIRED happens when you try to resume a session but the session ID has expired
    // SESSION_COMPLETED happens when you try to resume a session but the session has already been completed by the user
  });
</script>

Resuming Sessions

Each time you click on the <aiprise-button /> component and each time the <aiprise-frame /> component mounts, we create a new session. However in some cases, you may want to resume an old session.

For example you allow the user to go to another tab and come back. In such cases, you can provide us the old session ID and we will resume it directly instead of creating a new one.

<aiprise-button 
  id="my-verification-button"
  mode="SANDBOX/PRODUCTION"
  session-id="THE_ID_OF_THE_SESSION_YOU_WANT_TO_RESUME"
  template-id="YOUR_TEMPLATE_ID" <!-- This will be ignored when resuming but TypeScript requires this so always pass it -->
/>

<!-- Listen for Events -->
<script>
  var verifyButton = document.getElementById("my-verification-button");
  
  // Started Event
  verifyButton.addEventListener("aiprise:started", function (e) {
    // Access the session id like this => e.detail.verification_session_id
    // Save the session ID in this step. Give it back to the component when you want to resume.
  });
  
  // Resumed Event
  verifyButton.addEventListener("aiprise:resumed", function (e) {
    console.log("Session resumed with ID: " + e.detail.verification_session_id);
  });
</script>

This works the same way for both the button and frame component.

Updated 6 months ago