SDK Introduction

Introduction for SDK

IDCanopy SDK

This section explains how the UI based SDKs can be accessed once authentication is completed and a token has been created.

Handshake Request

The handshake request initiates a customer journey. Please note that:

• you define which components of the IDCanopy product offering you would like to consume with this request.
• you can configure each component as well as validation data.
• define the process name, which will appear on the invoice as billing item.
• You can enable a developer mode by switching on “magic_flow” in the handshake.

Request Structure:

{
  "journey": {
    "customer_id": "string",
    "process_name": "string"
  },
  "validation_data": {
    "full_name": "John Doe",
    "DOB": "1980-01-31",
    "Address": {
      "street_address": "123 Main Street",
      "locality": "Anytown",
      "region": "CA",
      "postal_code": "90210",
      "country": "US"
    },
    "IBAN": "DE11XXXX3245664",
    "phone_number": "+4915738901234",
    "unstructured_input": "This is some free unstructured text input for AI, OSINT and other analysis. John@doe.com aged 44, NHL player at Detroit RedWings; He might be in debt and has a Chinese Crested as dog."
  },
  "pass_through_data": {
    "user_id": "12345"
  },
  "steps": [
    {
      "interface": "Umbrella Canopy",
      "step": "Self KYC",
      "configuration": {
        "documentVerification": {
          "extraForensics": false,
          "biometricMatching": true,
          "liveness": true,
          "photoIdentPlus": false,
          "permitted_documents": {
            "allowed": [
              {
                "id_type": "passport"
              },
              {
                "id_type": "national_id",
                "bloc": "EEA",
                "excluded": [
                  {
                    "country": "DK"
                  }
                ]
              },
              {
                "id_type": "drivers_license",
                "country": ["BG"]
              }
            ]
          }
        }
      }
    },
    {
      "interface": "Umbrella Toolbox",
      "step": "AML",
      "configuration": {
        "SanctionPepAdverseMedia": {
          "monitoring": false,
          "dossier": true
        }
      }
    },
    {
      "interface": "Umbrella Toolbox",
      "step": "Phone Services",
      "configuration": {
        "Mobile Ident": {}
      }
    },
    {
      "interface": "Umbrella Toolbox",
      "step": "General",
      "configuration": {
        "IDV Protocol": {}
      }
    }
  ],
  "match_name": "strict",
  "match_dob": true,
  "magicflow": false,
  "validity_superpower": false,
  "journey_duration": "standard"
}
 

DTO Explanation handshake request

journey (object): Required. Defines the verification journey configuration.

• customer_journey_id (string): Required. Unique identifier for the customer journey.

• validation_data (object) (optional): Validation rules applicable to the entire journey The validation_data object houses various fields for different user data types, along with sample values for demonstration purposes. These fields are:

• full_name (string): A string containing the user's full name (e.g., "John Doe").

• DOB (string): A string representing the user's date of birth in YYYY-MM-DD format (e.g., "1980-01-31").

• Address: You can provide user address information in three ways:

  • Structured Object: For more granular control over address validation, consider using a structured object within validation_data:

address: 
{
 "street_address": "string",  // Street address line 1
 "locality": "string",       // City or town name
 "region": "string",          // State or province name (optional)
 "postal_code": "string",     // Postal code
 "country": "string"         // Country code (ISO 3166-1 alpha-2)
}

• • Single Line String: Alternatively, you can use a simple string for basic address validation (e.g., "123 Main Street, Anytown, CA 90210, US").
  • Google Maps API Short Address (string): You can also accept addresses in the Google Places API format. This typically includes a combination of locality, region, and postal code. Refer to Google Places API documentation for details on supported formats.

• IBAN (string): A string representing the user's International Bank Account Number (example uses a placeholder format, replace with actual IBAN).

• phone_number (string): A string containing the user's phone number in international format (e.g., "+4915738901234").

• unstructured_input (string): A string containing any additional user input you want to send for potential AI analysis by IdCanopy (e.g., email address, profession, etc.).

• pass_through_data (object) (optional): Additional data relevant to the entire journey (e.g., user ID, reference number).

• steps (array of objects): Optional, used to create journeys based on API instructions or to alter pre-defined journeys or combinations of journeys. If you have a pre-defined process from us, the process will work as defined without defining any steps. When using the manual step configuration however, you will need to define all steps yourself. Defines the sequence of verification steps within the journey (e.g., Self KYC, Address Verification, AML, SMS, IDV Protocol, IBAN Check,…).

• interface (string) (optional): (Consider for future expansion) Represents a high-level verification journey category (e.g., KYC, Identity Proofing).

• step (string): Required. Specific verification step within the journey (e.g., "Self KYC," "Address Verification").

• configuration (object): Optional. Step-specific configuration parameters (details depend on the chosen step).

  • [key: string]: object - Key represents the verification type (e.g., "documentVerification", "SanctionPepAdverseMedia"). Value is an object containing configuration options specific for that verification type.

• magicflow (boolean) (optional): Enables or disables a special verification flow (details might be specific to your IdCanopy integration).

• validity_superpower (boolean) (optional): Extends the validity of the ui_handle (used to initialize the verification frontend) from the default 5 minutes to 60 minutes. Please note that once the frontend has been initialized, there will be another counter that may limit the available time to complete the journey for the end-user.

• journey_duration (string) (optional): Sets the maximum duration before IdCanopy automatically closes the verification journey. You might enable a "continue later" option for the user so he can come back to the session later. Options include: -- "short": 150 seconds. -- "standard" (default if not specified): 300 seconds. -- "long": 600 seconds. -- "eternity": Disables automatic journey closure (use with caution).

Example for multiple validation data options in one structure

    {
    ...
    "validation_data": {
      "full_name": "John Doe",
      "DOB": "1980-01-31",  
      "Address": {
        "street_address": "123 Main Street",
        "locality": "Anytown",
        "region": "CA",  
        "postal_code": "90210",
        "country": "US"
      },
      "IBAN": "DE11XXXX3245664",  
      "phone_number": "+4915738901234",  
      "unstructured_input": "This is some free unstructured text input for AI, OSINT and other analysis. John@doe.com aged 44, NHL player at Detroid RedWings; He might be in debt and has a Chinese Crested as dog."
    }
...
    }

Additional API Behaviour settings

· match_name: (string) Defines name matching behavior during verification:

• "strict" (requires validation data to be passed)
• "fuzzy" (allows for some typos or variations)
• "none" (skips name matching)

· match_dob: (boolean) Enables DoB (date of birth) matching (requires validation data to be passed).

Handshake Response

The response structure includes essential information to proceed with the verification journey.

Properties:

• transaction_id (string): (Treat as Sensitive) Unique identifier for the verification journey assigned by IdCanopy. This identifier should be treated as sensitive data and not be directly exposed to the end-user. You can track the status of an ongoing transaction with that and it is also needed to identify the correct response.
• ui_handle (string): URL used to initialize the verification user interface for the customer. This URL is intended to be presented to the end-user to proceed with the verification process. This URL typically has a limited validity period (default: 5 minutes), which can be extended using the validity_superpower property in the DTO request. You'll integrate this URL into your frontend to launch the verification flow.

Response Structure:

{
  "transaction_id": "string",
  "ui_handle": "https://verification.idcanopy.com/init?verificationToken=VERIFICATION_TOKEN",
  "init_timestamp": "string"
}

Frontend Initialization

Iframe/Redirect Implementation Considerations:

• Iframe Embedding:

  • Create an iframe element and set its src attribute to the ui_handle.
  • Implement appropriate frame security headers (X-Frame-Options) on your server to restrict where the iframe can be embedded. This helps mitigate clickjacking vulnerabilities.

• Redirect Mode:

  • Use JavaScript's window.location.href to redirect the user's browser to the ui_handle.
  • Consider using a short-lived redirect (e.g., HTTP 302 Found) to minimize the time the URL is visible in the address bar, reducing the risk of sensitive information exposure.

Verification Flow:

• When the end-user's browser interacts with the process, you can listen to frontend events and react in your customer interaction.
• Upon completion of the verification flow, we push to the webhook you provided using the transaction_id as the identifier.

Frontend Event Listening

JavaScript Example:

const idcanopy = new IdCanopy();
const initUrl = getCustomerApiResponse().ui_handle;
idcanopy.init({ url: initUrl });
 
let lastActiveTime = Date.now();
const updateUserActivity = () => { lastActiveTime = Date.now(); }
 
document.addEventListener('mousemove', updateUserActivity);
document.addEventListener('keypress', updateUserActivity);
 
window.onbeforeunload = (event) => {
  const message = 'Are you sure you want to leave the verification process?';
  event.returnValue = message;
  return message;
};
 
idcanopy.on('journey_completed', (data) => {
  console.log('Journey completed:', data);
  // Update UI in iframe/redirected page to show success message
});
 
idcanopy.on('step_completed', (data) => {
  console.log('Step completed:', data);
  // Provide feedback to user (e.g., update progress bar, display messages)
});
 
idcanopy.on('fraud_alert', (data) => {
  console.log('Potential fraud alert:', data);
  // Display warning message, pause verification flow, and provide instructions
});
 
setInterval(() => {
  const inactiveTime = Date.now() - lastActiveTime;
  if (inactiveTime > 5 * 60 * 1000) {
    console.warn('User inactive for more than 5 minutes!');
    // Display warning message to user
  }
}, 60 * 1000);

Result Collection

Webhooks:

IdCanopy supports webhooks, a notification mechanism that allows you to receive real-time updates about customer journey progress.

Webhook Configuration:

1. Define Webhook URL: Specify the URL on your server that will handle incoming webhook notifications.
2. Register Webhook Events: Select the specific journey events you want to receive notifications for (e.g., journey completed, fraud alert).
3. Security: Implement appropriate security measures on your server to validate incoming webhook requests and protect sensitive data.

To properly receive incoming webhooks, your server should provide an endpoint supporting:

• TLS encryption version 1.2

• POST requests are either raw in text/plain if encrypted or application/json if no encryption is activated

You can use a service like e.g. https://webhook.site/ to test receiving webhooks from your developer dashboard. For local testing, you can use a CLI tool such as ngrok to forward the requests to your local development server.

When you receive an event, your endpoint should return a HTTP 2xx status code indicating that the event has been successfully received. Webhooks are automatically retried for up to 24 hours if no HTTP 200 status code is returned. The call will also be considered failed if your endpoint doesn't respond within 10 seconds.

When a webhook call fails, we'll retry the call 6 more times. By default, we wait 10 seconds between the first and second attempt, 100 seconds between the third and the fourth, 1000 between the fourth and the fifth and 10000 for the last attempt.

Security

Webhooks are a crucial node to ensure the functionality of your integration, as such, they can be the target of a malicious user aiming to disrupt the service or impersonate your users. In order to protect your application from these threats, a secret will be used to sign the request body.

We will add a header called Signature that will contain a signature of the event payload. You can use this signature to verify that the payload hasn't been manipulated. The signature is a HMAC using your Webhook Secret as a key and the SHA256 hash algorithm.

There will also be a header User-Agent with the value signteq.io API on each callback request to help you identify us.

This is how that signature is calculated (PHP example):

PHP

$payload = [ 'event' => 'request_signed' /// ... ]; $payloadJson = json_encode($payload); $signature = hash_hmac('sha256', $payloadJson, $secret);

Webhook Notification Example - finished transaction:

{
  "transaction_id": "e5c81c78-272b-4307-9197-3ace19109fd3",
  "customer_id":"g5481c79-ag2b-5313-9z95-3ape19779fuc",
  "timestamp": "2024-06-13T16:49:00+02:00",
  "status": "complete",
  "success": "PASS",
  "general_transaction_data": {
    "timestamp": "2022-02-14T10:04:32+01:00",
    "status": "complete",
    "success": "PASS"
  },
  "journey_summary": {
    "journey_stats": {
      "completed_steps": "2",
      "start_time": "2022-02-14T10:04:32+01:00",
      "end_time": "2022-02-14T10:06:38+01:00"
    },
    "identity_subject": {
      "type": "person",
      "full_name": "John Doe",
      "name_structure": {
        "first_name": "John",
        "last_name": "Doe"
      },
      "gender": "M",
      "nationality": "AT",
      "dob": "1981-12-24",
      "mobile_number": "+4312345678"
    },
    "authoritative_data": [
      {
        "type": "drivers_license",
        "id_number": "1234567",
        "issuing_date": "2015-06-18",
        "expiration_date": "2030-06-17",
        "expeditor": "LPD Wien/VA",
        "issuing_country": "AT"
      }
    ],
    "proof_of_work": [
      {
        "type": "image",
        "title": "selfie",
        "content_of_proof": "https://...",
        "timestamp_of_proof": "2024-06-13T16:49:00+02:00",
        "workstep_verification_source": "camera"
      },
      {
        "type": "image",
        "title": "document_front",
        "content_of_proof": "https://...",
        "timestamp_of_proof": "2024-06-13T16:49:00+02:00",
        "workstep_verification_source": "camera"
      }
    ],
    "steps": [...],
    "fraud_alerts": [...],
    "audit_trail": [...],
    "journey_documentation": {...}
  }
}

Data Structure & DTO Detail

This section describes the structure of the verification results response received through webhooks from the IdCanopy Journey API.

General Transaction Data:

Pass-Through Data:

This section contains optional customer-specific data passed through the verification journey.

Example:

"pass_through_data": {
  "bank_account_number": "1234567890"
}

Journey Summary:

Journey Stats

Identity Subject

Authoritative Data

Proof of Work

Steps

Fraud Alerts

Audit Trail

Journey Documentation

Example response

 
"VerificationResultsDTO": {
 " general_transaction_data": {
    "customer_journey_id": "e5c81c78-272b-4307-9197-3ace19109fd3",
    "timestamp": "2022-02-14T10:04:32+01:00",  
    "status": "complete",  
    "success": "PASS"
  },
  "journey_summary": {
    "journey_stats": {
      "completed_steps": "2",  
      "start_time": "2022-02-14T10:04:32+01:00",  
      "end_time": "2022-02-14T10:06:38+01:00",  
    },
    "identity_subject": {
      "type": "person",  
      "full_name": "John Doe",
      "name_structure": {
        "first_name": "John",
        "last_name": "Doe"
      },
      "gender": "M",  
      "nationality": "AT", 
      "dob": "1981-12-24",
      "mobile_number": "+4312345678"
    },
    "authoritative_data": [
      {
        "type": "drivers_license",
        "id_number": "1234567",
        "issuing_date": "2015-06-18",
        "expiration_date": "2030-06-17",
        "expeditor": "LPD Wien\/VA",
        "issuing_country": "AT"
      }
    ],
    "proof_of_work": [  
      {
        "type": "image",  
        "title": "selfie",  
        "content_of_proof": "https://...",  
        "timestamp_of_proof": "2024-06-13T16:49:00+02:00",  
        "workstep_verification_source": "camera"  
      },
      {
        "type": "image",  
        "title": "document_front",  
        "content_of_proof": "https://...",  
        "timestamp_of_proof": "2024-06-13T16:49:00+02:00",  
        "workstep_verification_source": "camera"  
      }
    ],
    "steps": [...],  
    "fraud_alerts": [..],  
    "audit_trail": [..],  
    "journey_documentation": {...}  
  }
}