Tax Information Collection & KYC

This flow enables a user to provide the information Tilia needs to substitute their W8 or W9 tax form and to run KYC (Know Your Customer), if needed. In the Token/Rev Share model, users receiving disbursements will need to complete the Tax Information Collection version of this form. In other cases, users may be required to complete the Full KYC form to receive payouts.

kyc flow

When a user opens this page, they will be asked to provide the following::

  • A valid email address
  • Their country or region
  • Personal information, including birthdate
  • Contact information, including address
  • (KYC Only) Extra files, in the form of identification documents (e.g., government-issued Photo ID, utility bill)

Upon completion, the data is submitted and the flow returns information describing the account's PII Level and KYC status. PII Level and KYC status are used to determine payout/disbursement eligibility. To receive disbursements, users must have a PII Level of “BASIC”. To request payouts, users must have a PII Level of “FULL” and a KYC state of “ACCEPT”.

Possible values for PII Level are:

Value Description
NONE The account has no associated PII.
BASIC The account's PII exists and can be used for tax purposes, but is not verified.
FULL The account's PII exists and its KYC state is ACCEPT.

Possible values for KYC Status are:

Value Description
NODATA No information has been collected for the account
NONE Information has been successfully collected for tax purposes, KYC has not been run.
PROCESSING KYC data is being actively processed.
ACCEPT The account's KYC data has been verified.
MANUAL_REVIEW The account's KYC data is under manual review by the Tilia Compliance Team.
DENY The account's KYC data has been rejected.
CANCEL Tilia's Compliance Team reached out to the user for more info and never received a response. User can submit new KYC application.
SYSTEM-CANCELLED Application cancelled by the system due to incorrect or incomplete information provided. User can submit a new KYC application.
REVERIFY (Legacy) User needs to resubmit a new KYC application.
attention

In some cases, users who have already submitted their Tax Information Collection form may be required to complete KYC. These users will receive a kyc_requirements value of “FULL_KYC”. Next time they open the KYC flow or the Payout Flow, the KYC form will be displayed and the user must complete it or any disbursements to their account will fail.

This flow begins with a check for a signed TOS. If one has not been signed, a TOS screen appears for a user to accept before proceeding with the flow.

Requirements

Requirement Description
ID of the <div /> element Your named <div /> in which the payment selection flow will be rendered
Redirect URL URL that initiates the flow

Supported flowConfig Options

Keys (all optional) Values Description
verificationLevel "basic_pii" Allows bypassing full 'KYC' when set to "basic_pii". Default (key is not included, or empty string) is to run the user through the full KYC flow.

Widget Flow Implementation

Use the following steps to open and customize this page in the widget:

  1. Copy the following code sample.
Copy
Copied
window.Tilia.execute({
    rootId: "<YOUR-ELEMENT-ID>"
    flow: "kyc",
    redirect: "<WIDGET-REDIRECT-URL>",
    onComplete: handleComplete,
    onError: handleError,
    theme: {
      backgroundColor: "#323232",
      primaryColor: "#47CC00"
    },
    flowConfig: {
      verificationLevel: "basic_pii"
    }
});
  1. Replace the placeholder values ( , ) with the values from the Requirements section.
  2. If your flow requires full KYC, remove verificationLevel: "basic_pii", from the widget script
  3. (Optional) In the theme object, customize the appearance of the widget.
attention

When setting verficationLevel with widget redirect pattern:

Copy
Copied
const url = "<REDIRECT_URL>?flow=kyc&returnurl=<YOUR_RETURN_URL>&"+encodeURI('flowConfig={"verificationLevel":"basic_pii"}')

Events

The Tax Information Collection / KYC flow fires the following events.

OnComplete

If the user submits Tax Information Collection:

Copy
Copied
{
  source: "tilia",
  event: "tilia.kyc.complete",
  state: "complete",
  result: "BASIC-PII-COLLECTED",
  trigger: "kyc-basic_pii_collected"
}

If the user completes KYC with a KYC status of ACCEPT:

Copy
Copied
{
  source: "tilia",
  event: "tilia.kyc.complete",
  state: "complete",
  result: "ACCEPT",
  trigger: "continue-button"
}

If the user completes KYC with any KYC status other than ACCEPT:

Copy
Copied
{
  source: "tilia",
  event: "tilia.kyc.complete",
  state: "cancel",
  result: "MANUAL_REVIEW", // or other possible KYC states
  trigger: "close-button"
}