Overview

Welcome to the developer documentation section.

In this page you will find a walkthrough of the Go.cam service, information about how it works and a guide on how you can implement it with your platform.

Hint: if you plan to use Go.cam, the first step would be to create an account. This will allow you to access our service as a partner and to configure the things needed for the implementation process. Please have a bit of patience for your account to be activated. It should not take more than 24 hours for that to complete.

Go.cam offers 3 types of verification designed to validate that the person is not a minor:

• credit card validity
• selfie age detection
• ID documents age extraction

The users can choose to use either of them when going trough a verification process.

Verification flow

From the point of view of a user, the verification process contain the following steps:

Fig: User verification flow schema

The user visits a partner site which is guarded by a age verification system

The user click on a button to start the age verification process

Depending on the type of Go.cam implementation:

• The user will be redirected to a URL on Go.cam where the verification process starts
• Will be presented with a iframe overlay that renders a Go.cam URL where the verification process starts

As mentioned above, there will be 3 types of verifications from which the user can choose in order to continue

Depending on the type of verification the user will have to provide credit card details, allow access to his webcam for scanning his face or select a ID document image for processing

Once the verification is complete, the user will be presented with a success or failure page:

• The success page will contain a button to return to the partner site
• The failure page will contain a "Retry" button so he can try again together with a QR code that can be scanned by a mobile device to continue the verification process there. If the verification on this second device succeeds, the original device from where the verification was initiated will be validated.

When the success button is clicked, the user will be redirected to the "link back" URL, the partner site should be unlocked

From the point of view of a partner who implemented Go.cam with a redirect logic, the verification process contain the following steps:

Fig: Redirect logic implementation schema

The user visits a partner site which is guarded by a age verification system

The user click on a button to start the age verification process

The partner provides the "cypher key" and "hmac key" to the Go.cam SDK together with some user data like a "user id" to generate a age verification URL

The user will be redirected to a URL on Go.cam where the verification process starts

Depending of the type of verification the user will have to provide credit card details, allow access to his webcam for scanning his face or select a ID document image for processing

Once the verification is complete, the user will be presented with a success or failure page:

• The success page will contain a button to return to the partner site
• The failure page will contain a "Retry" button so he can try again

The verification results will be saved on Go.cam

Go.cam will forward the verification results also to you defined "verification result callback url" together with the user data you defined like a "user id" so the partner cand mark the user as verified

Additionally a cookie is created on Go.cam containing a encrypted version of some of the verification results that can be decrypter on a future visit, using your encryption keys "cypher key" and "hmac key"

When the success button is clicked, the user will be redirected to the "link back" URL, the partner site should be unlocked

From the point of view of a partner who implemented Go.cam with a iframe logic, the verification process contain the following steps:

Fig: Iframe logic implementation schema

The user visits a partner site which is guarded by a age verification system

The user click on a button to start the age verification process

The partner provides the "cypher key" and "hmac key" to the Go.cam SDK together with some user data like a "user id" to generate a age verification URL

The partner uses also the frontend SDK to create a Go.cam verification instance and trigger the iframe overlay loading process

Once the iframe is loaded there will be an event anouncing it, aditionally if the iframe detects that a verification cookie was already set on Go.cam a different event will be triggered to announce it (in this case a verification is no longer needed usually but a cookie integrity check must be performed)

Depending of the type of verification the user will have to provide credit card details, allow access to his webcam for scanning his face or select a ID document image for processing

Once the verification is complete, the user will be presented with a success or failure page:

• The success page will contain a button to close the iframe overlay
• The failure page will contain a "Retry" button so he can try again

The verification results will be saved on Go.cam

Go.cam will forward the verification results also to you defined "verification result callback url" together with the user data you defined like a "user id" so the partner cand mark the user as verified

Additionally a cookie is created on Go.cam containing a encrypted version of some of the verification results that can be decrypter on a future visit, using your encryption keys "cypher key" and "hmac key"

Finally a javascript event will be triggered to anounce the verification success which can be used optionally as a trigger to verify the cookie integrity saved in the previous step

When the success button is clicked, the iframe overlay is removed and the partner site should be unlocked

Legend:

• partner: you, the one who implements Go.cam on your platform
• cypher key and hmac key: keys found in your Go.cam user account, used for the encryption process of the data we use during the verification process
• verification result callback url: a url you define in your account, used by Go.cam to post back results to your server at the end of a verification process
• link back: a url you define using the Go.cam SDK, used for the redirect after a succesfull verification

Verification types

Credit card verification

The credit card verification will redirect temporary the user to a secure environment where his credit card number and expiration date will be asked. The user will not be charged with anything, only the validity and itegrity of the credit card is checked for this test. This is the only type of verification that send some data to the backend for verification in a secure PCI DSS compliant environment. Go.cam will not store any of this data on it servers or forward it to any partner.

Selfie age verification

The selfie age verification check needs webcam access in order to scan in real time the face of the user. So the user must provide this access in order for the verification to run. During the verification the user will be asked to keep his face close to the center of the screen in order for the machine learning model to be able to perform the face extraction and the prediction task. Go.cam runs locally, on device, no images are sent to the server or stored during this process.

The age prediction is based on multiple shots of the users face from which an average age is calculated after the detected outliers are excluded. Besides the age evaluation, the face similatity is checked during the detection to be sure the same person is in front of the camera at all times. At the end of the verification, if the user is detected as an adult, he will also be asked to smile or stop smiling, depending on his current face expression, as a measure of liveness detection.

If the user is detected as an minor, the verification process will automatically redirect him to the ID document verification to confirm his age. During the ID verification the face shots from the previous steps are compared with the one from the document as a first step. Then if the face matching is correct the birth date will be extracted from the document and the age will be calculated based on that.

If the user is detected as an adult after the selfie age or the ID document verification process, he will be marked as verified. Otherwise the process can be retried, for a period of 10 minutes, the current session will expire after that so the process must pe restarted from the start.

Hint: Go.cam is "Challenge 25" certified, meaning that anyone who is over 18 but looks under 25 should carry acceptable ID document to validate his age.

Authorities that already certified us are:

• Central Authority for the Supervision and Protection of Minors on the Internet in Germany
• Age Check Certification Scheme

For the age verification task Go.cam uses a implementation of a open source facial recognition model, you can find more about it here.

ID documents verification

As a first step of this verification, the user will be asked to select from a list of countries and document types to match the document he is planning to provide as proof. Currently Go.cam supports documents from all European countries and the United States of America. The supported types of documents are: ID card, passport and driver license.

The ID documents verification check can be done with the help of a webcam or by loading locally a image of a valid document. The user is not forced to provide webcam access, if he denies it he will be asked to browse for a image as default. Taking a photo with the webcam or selecting a local one will not trigger an upload of the image, like the age verification, the process will run locally.

In the case of a ID document verification that is not preceded by a selfie age verification, the face of the person on the document will not be checked. The birthdate of the document will be extracted and the current age of the user will be calculated. Based on the country or state the document is from, there is also a age majority check done. A verification success is triggered if the detected age is greater than the majority age.

For the document birthdate extraction task Go.cam uses a implementation of a open source OCR model, you can find more about it here.

Implementation examples

Currently, we provide 2 examples of implementation of Go.cam. The implementation programming languages are PHP and Javascript.

Verification using redirect library

Used for generating a Go.cam verification URL, based on your access keys. This library can be used in a stand-alone way if you plan to do the age verification in a new browser window or using a redirection.

Hint: A example implementation can be downloaded from here.

This implementation should be simple and easy to understand from the examples.

Here is a quick walkthrough:

We provide a php class that should handle all the operations you need to run for running Go.cam. So the first step would be to require this class in your implementation.

				
require_once 'avsPhpSdkV1.php';
				
			

Next you need to initialize this helper class using the information you can retrieve from your Go.cam account.

				
$partnerId = {Age verification account id};
$cipherKey = {Cipher key};
$hmacKey   = {Hmac key};

$avsInstance = new AvsPhpSdkV1(
	$partnerId,
	$cipherKey,
	$hmacKey
);
					
			

You can also set a language, which defaults to english. Setting a language will render a test page in that specific language.

Currently the supported languages are:

• English
• French
• German
• Dutch
• Italian
• Portuguese
• Spanish

				
$avsInstance->setLanguage(AvsPhpSdkV1::LANGUAGE_EN);
				
			

Go.cam uses a "aes-256-cbc" encryption system to encrypt data during a verification process. So, for each verification session, a encrypted payload is created and passed from the partner to Go.cam. This payload has the role to send data securely between both parties.

To create the payload and bundle it as a string inside a GO.cam url we must first define it's data. The array structure you can see below is an example. Some of the parts are optional, some are mandatory and there is also a way to pass some custom data that you can get back on your callback request.

Here is an example:

				
$avsInstance->fillRequest(
	array(
		// mandatory: this will be posted back to the parther as is
		'userData' => array(
			// mandatory: partner internal user id, used for tracking the user
			'userId' => $userId,
			// optional: some custom data the partner want to include in this verification session
			'someCustomData' => true,
			// optional: custom colors for the interface of the Go.cam verification process
			'colorConfig' => array(
				'body' => array(
					'background' => $colorConfigBodyBackground,
					'foreground' => $colorConfigBodyForeground,
					'button' => array(
						'background' => $colorConfigButtonBackground,
						'foreground' => $colorConfigButtonForeground,
						'foregroundCallToAction' => $colorConfigButtonForegroundCTA,
					)
				),
			)
		),
		// mandatory: parameters related to the http request
		'http' => array(
			// mandatory: the user agent of the user
			'userAgent' => $userAgent,
			// mandatory: the hostname from which the verification process is initiated
			'websiteHostname' => $websiteHostname,
			'paramList' => array(
				// optional: a way to control if the detected age number is shown on the screen during the selfie age verification process
				'showDetectedAgeNumber' => $showDetectedAgeNumber
			)
		),
		// optional: the Go.cam verification version
		'verificationVersion' => AvsPhpSdkV1::VERIFICATION_VERSION_STANDARD_V1,
		// mandatory: the URL to get back to the partner site after a verification
		'linkBack' => $linkBack,
		// optional: ip of the user
		'ipStr' => $userIp,
		// optional: ISO country code of the user
		'countryCode' => $countryCode,
		// optional: ISO state code of the user (used for US mostly)
		'stateCode'  => $stateCode,
	)
);

$verificationUrl = $avsInstance->toUrl();
				
			

The last step is to create a html link to point to this verification URL somewhere on the partner page.

				
<a href="<?php echo $verificationUrl; ?>" target="_blank">Start age verification</a>
				
			

The postback URL points to a partner server address which should contain a custom script to receive and parse the data Go.cam sends back to it. See a description of the Backend callback url data list below.

Verification using iframe library

An addition to the redirect library, used to handle the iframe overlay of Go.cam, control the resource load and trigger events about the lifetime and result of the age verification process.

Hint: A example implementation can be downloaded from here.

Here is a quick walkthrough:

The first part of this implementation is exactly the same as the "Verification with redirect" process described above. The only difference is that for this case is that the verification URL is different. For this case we need to create a iframe verification URL instead.

So instead of calling "toUrl"

				
$verificationUrl = $avsInstance->toUrl();
				
			

we will call the method "toIframeUrl" instead.

				
$verificationUrl = $avsInstance->toIframeUrl();
				
			

More changes are required on the frontend in order for this implementation to fully work. First let's include the helper class we provide for the frontend part:

				
<script src="avsJsSdkV1.js"></script>
				
			

A trigger button for the iframe overlay is also needed:

				
<button id="openVerificationIframeButton" disabled>Open verification iframe</button>
				
			

The rest of the implementation is done in the frontent. We need next to initialize the frontend library and define it's parameters.

				

// define the trigger button instance
var openVerificationIframeButton = document.querySelector('#openVerificationIframeButton');

// define the iframe verification url generated with the php library above
var iframeUrl = '';

// initialize the js sdk config
AvsJsSdk.V1.Config.create({
    iframeLocationUrl: iframeUrl
});

// create a js sdk library instance
var avsInstance = new AvsJsSdk.V1.Core();

// initialize the js sdk library
avsInstance.init();

				
			

Once the frontend library it's initialized it will start to trigger various events and be able to receive itself some events. These events are described below in the Front end library event callback list section.

We can listen for events by using the "onMessage" method, or emit events back to it using the "emit" method. Based on these events the partner should create a verification logic like it is shown below:

				

// handle the iframe messages
avsInstance.onMessage = function (eventMessage) {

    switch (eventMessage.name) {

        // check phase: iframe was loaded
			case AvsJsSdk.V1.Config.EVENT_ON_CHECK_IFRAME_LOADED:

				// send an event to the iframe for starting the verification process check phase
				avsInstance.emit(AvsJsSdk.V1.Config.EVENT_STATUS_REQUEST);

				break;

        // check phase: age verification was successful on a previous verification process, user is already verified
        case AvsJsSdk.V1.Config.EVENT_ON_INITIAL_VERIFICATION_SUCCESS:

            // in the case of a success event, the cookie integrity should be also checked
            payloadIntegrityCheck(eventMessage.data.payload, function(data) {
                if (data.error) {
                    appendToLog(data.error.msg);
                    return;
                }
            });

            break;

        // check phase: age verification was not successful on a previous verification process or did not run at all
        case AvsJsSdk.V1.Config.EVENT_ON_INITIAL_VERIFICATION_NOT_FOUND:

            // in the case there was no initial verification found, we can start the iframe resources load process
            avsInstance.emit(AvsJsSdk.V1.Config.EVENT_RESOURCE_PRELOAD);

            break;

        // verification phase: verification fatal error, payload was incorrect or resource load failed
		case AvsJsSdk.V1.Config.EVENT_ON_INITIAL_VERIFICATION_FATAL_ERROR:

            // TODO: trigger and error or restart the process

            break;

        // verification phase: iframe was loaded (resources are still loading)
        case AvsJsSdk.V1.Config.EVENT_ON_START_PAGE_LOADED:

            break;

        // verification phase: iframe resources were loaded
        case AvsJsSdk.V1.Config.EVENT_ON_RESOURCES_LOADED:

            // enable the "start verification" button
            openVerificationIframeButton.disabled = false;

            // attach an click event to the "start verification" button
            openVerificationIframeButton.addEventListener('click', function () {
                // show the verification iframe as an overlay
                avsInstance.iframeInstance.expand();
            });

            break;

        // verification phase: iframe overlay close button was clicked
        case AvsJsSdk.V1.Config.EVENT_ON_CLOSE_IFRAME:

            // hide the verification iframe overlay (it's still running in the background)
            avsInstance.iframeInstance.collapse();

            break;

        // verification phase: verification process was successful
        case AvsJsSdk.V1.Config.EVENT_ON_VERIFICATION_SUCCESS:

            // disable the "start verification" button
            openVerificationIframeButton.disabled = true;

            // in the case of a verification success event, the cookie integrity should be also checked
            payloadIntegrityCheck(eventMessage.data.payload, function(data) {
                if (data.error) {
                    appendToLog(data.error.msg);
                    return;
                }
            });

            break;

        // verification phase: verification process failed
        case AvsJsSdk.V1.Config.EVENT_ON_VERIFICATION_ERROR:

            // verification was completed with error, this is a optional event, the verification can be retried inside the iframe

            break;

    }

}

				
			

The "payloadIntegrityCheck" method is a ajax call to a URL on the partner site. The check implementation can be found in the library .zip file, inside the file "payloadIntegrityCheck.php".

				
var payloadIntegrityCheck = function (verificationResultPayload, callback) {

    postAjax(
        'payloadIntegrityCheck.php',
        {
            verificationResultPayload: verificationResultPayload
        },
        function (data) {
            callback(JSON.parse(data));
        }
    );

}
				
			

You can find both implementations from above inside your Go.cam account, as a example.

Front end library event callback list

In the case you implemented the "Verification using iframe library" the frontend library might trigger one of the events from below during a verification process. It is up to the partner to handle these events on his platform as he sees fit for his users experience.

				
AvsJsSdk.V1.Config.EVENT_ON_CHECK_IFRAME_LOADED
				
			

This is the first event that is triggered by the iframe, it's triggered when the iframe document is ready.

				
AvsJsSdk.V1.Config.EVENT_STATUS_REQUEST
				
			

Request the age verification iframe the status of the cookie, works only on the initial verification phase.

				
AvsJsSdk.V1.Config.EVENT_ON_INITIAL_VERIFICATION_SUCCESS
				
			

The verification cookie it's already present on the user's browser due to a previous successful verification process.

				
AvsJsSdk.V1.Config.EVENT_ON_INITIAL_VERIFICATION_NOT_FOUND
				
			

The verification cookie was not found, meaning the user did not yet completed a successful verification process.

				
AvsJsSdk.V1.Config.EVENT_RESOURCE_PRELOAD
				
			

Request the age verification iframe to start loading the verification phase and it's needed resources.

				
AvsJsSdk.V1.Config.EVENT_ON_INITIAL_VERIFICATION_FATAL_ERROR
				
			

The specified access keys were incorrect or the go.cam resources failed to load.

				
AvsJsSdk.V1.Config.EVENT_ON_START_PAGE_LOADED
				
			

The age verification page document it's ready, the resources are still loading.

				
AvsJsSdk.V1.Config.EVENT_ON_RESOURCES_LOADED
				
			

The age verification page resources finished to load.

				
AvsJsSdk.V1.Config.EVENT_ON_CLOSE_IFRAME
				
			

The iframe overlay close button was clicked.

				
AvsJsSdk.V1.Config.EVENT_ON_VERIFICATION_SUCCESS
				
			

The age verification process was completed with success.

				
AvsJsSdk.V1.Config.EVENT_ON_VERIFICATION_ERROR
				
			

The age verification process was completed with error.

Backend callback url data list

Once a verification process is complete with success of with failure a server to server postback will be done in order to notify the partner about it. The postback is in a form of a array, like the one below:

				
array(
	'userData' => array(
		'userId' => 123,
		'colorConfig' => array(
			'body' => array(
				'background' => '#900',
				'foreground' => '#fff',
				'button' => array(
					'background' => '#fb0',
					'foreground' => '#333',
					'foregroundCallToAction' => '#700',
				)
			)
		)
	),
	'state' => 'success',
	'stateInt' => 2,
	'sessionId' => 12345,
	'errorCode' => 0,
	'deviceType' => 1,
	'stepId' => 2,
	'websiteHostname' => 'your-site-name.cam',
	'ip' => '127.0.0.1',
)
				
			

Here is a explanation of possible array keys:

				
'state' => 'success'
				
			

Possible value	Meaning
success	the verification was successful
fail	the verification failed

				
'stateInt' => 2
				
			

Possible value	Meaning
0	unknown
1	Test not started or aborted
2	Success
3	Failed
4	Link expired
5	Link already used

				
'sessionId' => 12345
				
			

Possible value	Meaning
12345	Verification session id

				
'errorCode' => 0
				
			

Possible value	Meaning
0	No error
25001	Device it is not supported
25032	Preloading verification resources failed (face api resources)
25033	Preloading verification resources failed (tesseract resources)
25034	Could not retrieve your device camera list (selfie detection camera selection step)
25055	Could not detect enough faces from the device video (age detected is 0)
25056	Face similarity check fail (all selfie faces comparison)
25057	Could not detect enough faces from the device video (0 faces detected)
25061	Could not detect enough faces from the device video (expression check fail)
25062	Face similarity check fail (expression faces comparison)
25047	Webcam initialization error (selfie detection step)
25035	Failed to initialize detection libraries (selfie detection step -> face api detector)
25036	Failed to initialize detection libraries (selfie detection step -> face api age model)
25037	Failed to initialize detection libraries (selfie detection step -> face api recognition model)
25038	Failed to initialize detection libraries (selfie detection step -> face api landmarks model)
25058	Failed to initialize detection libraries (selfie detection step -> face api expression model)
25039	Could not retrieve your device camera list (scan id detection camera selection step)
25040	Failed to initialize detection libraries (scan id detection step -> tesseract worker)
25041	Failed to initialize detection libraries (scan id detection step -> tesseract language model)
25042	Failed to initialize detection libraries (scan id detection step -> tesseract language init)
25043	Failed to initialize detection libraries (scan id detection step -> tesseract worker config)
25044	Failed to initialize detection libraries (scan id detection step -> face api detector)
25045	Failed to initialize detection libraries (scan id detection step -> face api recognition model)
25051	Failed to extract a face from your identity card
25052	Selfie face does not match the one found on the identity card
25053	Detected age is lower than 18 years (scan id detection step)
25054	Failed to extract your age from the current identity card
25046	Webcam initialization error (scan id detection step)
20002	Test max allowed time expired (test success callback)
20004	Invalid step id (test success callback)
20000	Invalid token (test success callback)
20034	Invalid xcore api curl response (test success callback)
20003	Test max allowed time expired (test fail callback)
20005	Invalid step id (test fail callback)
20001	Invalid token (test fail callback)
20035	Invalid xcore api curl response (test fail callback)
20036	Detected age is lower than 18 years (Opale.io detection step)
18001	Credit card verification internal error
18002	Credit card verification maxmind error

				
'deviceType' => 1
				
			

Possible value	Meaning
0	unknown
1	mobile
2	desktop

				
'stepId' => 2
				
			

Possible value	Meaning
0	Test not started or aborted
1	Start page
2	Selfie detection camera selection
3	Selfie detection
4	Scan id camera selection
5	Scan id detection
6	Credit card verification intro
7	Credit card verification page

				
'idCountry' => 'FR'
				
			

Possible value	Meaning
FR	Country short code of the document the user selected to provide for the verification

				
'idState' => 'TX'
				
			

Possible value	Meaning
TX	State short code of the document the user selected to provide for the verification

				
'idType' => '1'
				
			

Possible value	Meaning
1	Id card
2	Passport
3	Driver licence

				
'websiteHostname' => 'your-site-name.cam'
				
			

Possible value	Meaning
your-site-name.cam	Host name from where the test was initiated

				
'ip' => '127.0.0.1'
				
			

Possible value	Meaning
127.0.0.1	Ip from where the test was initiated