Usage

How to use the Smile ID Web Integration

Steps

1. Fetch the web token from your server, when ready

2. Configure the web integration

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 ID products. "biometric_kyc" "doc_verification "authentication" "basic_kyc" "smartselfie" "enhanced_kyc" "enhanced_document_verification" "e_signature"
document_ids	array	Yes (for e_signature)	a list of previously uploaded document IDs
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"] }
document_capture_modes	array	No	list containing camera or upload or both defaults to camera

* - 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, enhanced_document_verification, 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 ID 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.