Last updated 1 day ago

KYC integration guide

Gathering docs

Your AppCustomerRebillypasswordless loginlogin tokenexchange token with limited ACLA customer-scoped storefront token (JWT)Click to "KYC"redirect with JWT to "KYC document gatherer"File (identity document)File token referenceAnalyze document by reference tokenDocument rejected, correction suggestion (...)All goodalt[is rejected][is good]RedirectYour AppCustomerRebilly
  1. Look up a customer ( and create one if not found).
  2. Generate a passwordless login token. We recommend using passwordless for this KYC document gatherer experience (which means you have already authenticated your customer in some other way -- such as they have logged into your website).
  3. Exchange the login token for a storefront API token (JWT). We would recommend to limit the access for the customer to only the required API operations for the KYC document gatherer.
  {
      "acl": [
        {
          "scope": {
            "organizationId": [
              "replace_with_organization_id"
            ]
          },
          "permissions": [
            "PostFile",
            "StorefrontGetWebsite",
            "StorefrontGetAccount",
            "StorefrontGetKycDocumentCollection",
            "StorefrontGetKycDocument",
            "StorefrontPostKycDocument"
          ]
        }
      ],
      "customClaims": {
          "documents": ["identity-proof", "address-proof", "funds-proof"],
          "redirectUrl": "https://mywebsite.com",
      },
  }
  1. Form the KYC document gatherer link. It is composed of parts:
Part Description
server name Our sandbox app server is demo.comply.services. Our live app server is verification.comply.services. If you made a custom app, it will live at a different server name.
token This token is the storefront JWT. First, you need to Generate a login token. The KYC document gatherer experience is geared for a passwordless token when the customer is already authenticated in your system.
Specify the accepted document types by setting the documents array. Valid types are identity-proof, address-proof, and funds-proof. To collect multiple identities, supply multiple identity-proof values in the array. Example: ["identity-proof", "address-proof", "funds-proof"].
Set the redirect URL by setting the redirectURL. At the end of either 3 bad attempts or a success, the customer will be redirected to the redirectUrl.
Determine how long the token is valid for by setting the expiredTime (for example, set it 1 hour in the future for it to be valid for 1 hour, 1 day in the future for it to be valid for 1 day). The recommendation is to keep it shorter when linking from a logged-in user-interface, and longer when linking from an email. Then, exchange it for a customer-scoped JWT storefront token.
https://{server name}/?token={storefront JWT token}

Here is a real fully-formed URL (which has already expired):

https://demo.comply.services/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJMNndIO...AS9LH8JJQ82aNqA

Finally, redirect your customer to the link, or present them with a call to action to start the KYC process.

When the KYC process is finished, the customer will be redirected to the redirectUrl with the reason code in the info query parameter.

https://{redirectUrl}/?info={the reason code}

The info parameter may have one of the following values:

  • back - The customer clicked the back to website link;
  • token_expired - The customer's token expired;
  • success - The customer uploaded docs that were successfully analyzed;
  • manual - The customer uploaded docs that will require manual review because the analyzer rejected them or couldn't process them;
  • partial - The customer had success with some doc type but not with other (for example, successful proof of address but skipped proof of id);

Webhooks

Use webhooks to stay updated about the status of KYC documents. Subscribe to these events:

kyc-webhooks-setup

Learn more about webhooks