Smile Identity
Search
⌃K

Usage

How to use the Smile Identity Web Integration

Steps

  1. 1.
    Fetch the web token from your server, when ready
  2. 2.
    Configure the web integration
  3. 3.
    Test the Integration

Fetch the Web Token from your server

Using the Web Token endpoint set up on your server, fetch a web token for the client
This can take the form of a click event on your web site or application.
const baseAPIURL = `${your-API-server-URL}`;
const getWebToken = async (baseAPIURL) => {
const fetchConfig = {}
fetchConfig.cache = 'no-cache';
fetchConfig.mode = 'cors';
fetchConfig.headers = {
'Accept': 'application/json',
'Content-Type': 'application/json'
};
fetchConfig.method = 'POST';
const URL = `${baseAPIURL}/token/`;
try {
const response = await fetch(URL, fetchConfig);
if (response.status === 200 || response.statusCode === 200) {
const json = await response.json();
if (json.error) {
throw new Error(json.error);
}
return json;
}
} catch (e) {
console.log(`API: ${e.name}, ${e.message}`);
throw e;
}
};
const verifyWithSmileIdentityButton = document.querySelector('#verify-with-smile-id');
verifyWithSmileIdentityButton.addEventListener('click', async e => {
e.preventDefault();
verifyWithSmileIdentityButton.textContent = 'Initializing session...';
verifyWithSmileIdentityButton.disabled = true;
const { token } = await getWebToken(baseAPIURL);
}, false);

Configure the Web Integration

With the web token, we can now configure our integration
const configureSmileIdentityWebIntegration = (token) => {
SmileIdentity({
token,
product: "biometric_kyc",
callback_url: `${your-API-server-URL}/callback`,
environment: "sandbox",
partner_details: {
partner_id: `${your-smile-identity-partner-id}`,
name: `${your-app-name}`,
logo_url: `${your-app-logo-url}`,
policy_url: `${your-data-privacy-policy-url}`,
theme_color: '#000'
},
onSuccess: () => {},
onClose: () => {},
onError: () => {}
});
};
// ACTION: call the initialization function in the event handler
verifyWithSmileIdentityButton.addEventListener('click', async e => {
e.preventDefault();
verifyWithSmileIdentityButton.textContent = 'Initializing session...';
verifyWithSmileIdentityButton.disabled = true;
try {
const { token } = await getWebToken(baseAPIURL);
configureSmileIdentityWebIntegration(token);
} catch (e) {
throw e;
}
}, false);
The API for configuring the integration is as follows
Key
Type
Required
Description
token
string
Yes
token generated on the server side using the get_web_token method in one of our server-to-server libraries
product
string
Yes
one of the smile identity products. "biometric_kyc" "doc_verification "authentication" "basic_kyc" "smartselfie" "enhanced_kyc"
callback_url
string
Yes
a callback URL on your API server or wherever you prefer.
environment
string
Yes
one of "sandbox" or "live"
partner_details
object
Yes
customizations for your organization. details here
onSuccess
function
No
function to handle successful completion of the verification.
onError*
function
No
function to handle errors with verification, called when end-user consent is denied
onClose
function
No
function to handle closing of the verification process
id_selection**
object
No
a mapping of country code to a selection of supported id types e.g.
{
"NG": ["BVN_MFA", "V_NIN"]
}
consent_required ***
object
Yes, for ID Types where user consent is required.
a mapping of country code to a selection of supported id types e.g.
{
"NG": ["BVN", "NIN"]
}
* - onError function can take one argument of the shape { message: <message>, data: <object with details> }
** - id_selection list is checked against those enabled for your partner account. this is limited in cases of basic_kyc, enhanced_kyc, and biometric_kyc.
If you pass only one country and id type in theid_selection object, the id type selection screen will not be displayed in the web integration instance
*** - consent_required list is subject to the ID Authority configuration. some ID Authorities require end-user consent, and that requirement overrides this setting

partner_details configuration reference

Key
Type
Required
Description
name
string
Yes
Application Name
partner_id
string
Yes
Smile Identity Partner ID
policy_url
string
Yes
URL to data privacy policy
logo_url
string
Yes
URL to App Logo (best in 1:1 aspect ratio)
theme_color
string
No
a valid CSS Color Code for accent colors

Test the Integration

After configuring the integration, you can walk through an example.