Last updated 1 month 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.
      "permissions": [
          "documents": ["identity-proof", "address-proof", "funds-proof"],
          "matchLevel": 1,
          "reason": "string",
          "redirectUrl": ""
  1. Form the KYC document gatherer link. It is composed of parts:
Part Description
server name Our sandbox app server is Our live app server is 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, purchase-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 match-level to specify how strict or relaxed the requirements will be in order to complete the request. Valid entries are 1 for a relaxed check or 2 for a strict test. If no value is set, 2, or strict, is the default value.
Optionally, set the reason for uploading with any string.
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):

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);


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


Learn more about webhooks