Skip to main content

Integration

This section explains how to deploy a privacy-preserving KYC workflow into your application. You need to make changes on both the front end and back end of your application, as well as understanding how to use the information from the webhooks.

How it works​

You integrate ComPilot into your application (a client and server) by using the ComPilot SDKs.

  1. Your server exposes a custom endpoint (with the help of the JavaScript SDK) that allow the user to open authenticated ComPilot sessions. This endpoint is using your own private API key.
  2. The front end SDK (either the Web SDK or the React SDK) uses this endpoint to open an authenticated session with ComPilot.
  3. Through the ComPilot widget, your client collects data from the customer and sends it to ComPilot.
  4. ComPilot sends the customer's data to third-party providers for verification and screening.
  5. ComPilot receives information from the third party providers and evaluates it by using the rules you created in the ComPilot Rules Engine.
  6. Using the webhooks, ComPilot sends updates, such as the event type and customer ID, to your server.
  7. Your server can then use the ComPilot API to get more information from ComPilot, such as their wallet or name, or to update the customer's details.

Integration strategies​

There are two key decisions to make for your integration strategy: which SDKs to use, and whether to use the regular or Web3 flows.

SDKs​

On the client side, you can use either the Web SDK or the React SDK.

  • Use the React SDK if you build your front end in React.
  • Use the Web SDK if you build your front end in JavaScript or another JavaScript framework.

On the back end, you can use either the JavaScript SDK or you can use the ComPilot API directly.

Using the SDKs is described in SDKs.

Regular and Web3 modes​

An identity verification workflow can run in Regular or Web3 mode.

  • Regular mode allows customers to verify their identity without a Web3 wallet. This is used when your customers do not need a self-custodial web3 wallet to interact with your application.
  • Web3 mode requires customers to authenticate using their Web3 wallet.

There are three benefits to Web3 mode:

  • You can link your customers' real-world identity with their Web3 wallets.
  • Customers' wallets can automatically screened with an onchain screening tool connected to ComPilot.
  • At the end of verification, customers are issued reusable KYC reports that can be controlled using their Web3 wallets.

Web3 mode is the preferred mode for dApps.

For more information, see Regular and Web3 modes.

Initial back end changes​

There are two things you have to do in the back end of your app.

  1. Configure API endpoints to receive webhooks. For full details of webhooks and their events, see Webhooks.

    The customer.updated events are extremely important. When you receive a customer.updated event, you can use the ComPilot API to retrieve the customer's details from ComPilot and update your customer database. For an example, see When the customer gets KYC approval. In particular, you should use customer.updated events to track changes in the customer's status, particularly if they have changed to or from Active or Rejected.

    note

    The structure of the validation result could vary, depending on the rules, but it will still have all the necessary flags to determine whether the customer meets the requirements so that your app can allow or deny access the customer.

  2. If the customer is trying to perform an action that requires verification, check if they are verified in your records.

    • If the customer is verified and on the allowed list, let them proceed to the action.
    • If the customer is verified and on the blocked list, block them.
    • If not verified, initiate the ComPilot data request.

Once you have done these, there are additional changes that you need to make in both the front and back ends.

Completing the integration and using the SDKs​

The next steps depend on how you are using ComPilot.

Gating the application​

ComPilot returns a result that tells your application whether a customer should be allowed access to the gated part of your application. You have to write the code that allows or denies the customer access based on the result that ComPilot returns.

The result can be generated automatically by the ComPilot Rules Engine, but you can also manually check the customer's details on the ComPilot Dashboard to make a decision asynchronously.

Using the webhook payload​

Each payload contains the ID of the relevant resource. When a payload is received, the application should use the ComPilot API to get data connected with the resource.

See Customers endpoints, and Alerts endpoints for more information.

tip

The payload may contain country information in ISO 3166-1 alpha-3 format.

Example: when the customer gets KYC approval​

  1. When a customer starts a KYC process, your application has their web session details and their wallet address.

  2. As they go through the KYC process, several webhook events of various types are created.

  3. When the customer gets KYC approval, a customer.updated event is sent to the webhook. The payload includes the customer status with a value of Active ("status": "Active") the customer ID in the ComPilot Dashboard (customerID) and the customer ID in your system (externalCustomerId).

    {
        "eventType":"customer.updated",
        "payload":{
            ...
            "status": "Active",
            ...
            "customerId":"bc9923ef-37a4-4478-8dca-3bae58049674",
            ...
        }
    }

    The externalCustomerId is the ID of the customer ID in your system that you passed in when creating a session (see Integration). You can use this value to determine which user this payload refers to on your system.

  4. If your application needs additional information about the customer, it can use the Get customer details by customerId endpoint to get all the customer's details.

    In the following example, <customerId> should be replaced by the value of customerId, and <TOKEN> is your API key. See ComPilot API.

    const https = require('follow-redirects').https;
    const fs = require('fs');

    let options = {
      'method': 'GET',
      'hostname': 'api.compilot.ai',
      'path': '/customers/<customerId>/details',
      'headers': {
        'Accept': 'application/json',
        'Authorization': 'Bearer <TOKEN>'
      },
      'maxRedirects': 20
    };

    const req = https.request(options, (res) => {
      let chunks = [];

      res.on("data", (chunk) => {
          chunks.push(chunk);
      });

      res.on("end", (chunk) => {
          let body = Buffer.concat(chunks);
          console.log(body.toString());
        });

      res.on("error", (error) => {
         console.error(error);
      });

    });

    req.end();

    The response from the endpoint will contain all the customer's details. You can then populate your database with this information.