# Introduction
Treezor is legally obligated to verify the identity of the users using its services, whether it's you as a company or your end users.
The obligations placed on banking services providers aim to prevent the misuse of the financial system for illegitimate purposes, as stated by the anti-money laundering and countering the financing of terrorism (AML/CFT) rules.
In this context, Treezor collaborates closely with regulating institutions through reporting and monitoring, and any other measure that aims to provide a compliant and secure banking ecosystem.
Once your project is approved and you start using your Production environment, you must abide by the same rules and regulations.
# KYC / KYB
The terms Know Your Customer (KYC) and Know Your Business (KYB) refer to the verification of a user, whether they are a legal entity or an individual.
For Treezor to make sure users are who they say they are, you need to provide:
- Declarative data – Regarding the user, such as their name, address, etc.
- Documents – Proving the user or entity identity (IDs, company registration, proof of address, etc.)
The KYC / KYB of a user is not a one-time check. In addition to the initial check done during the end-user onboarding, multiple reviews are made along the user lifecycle.
The requirements to verify a user identity vary depending on factors such as:
- The type of services you provide
- The country you’re operating in
- The type of users to be verified
Some additional vigilance measures are required, such as a SEPA Transfer to a Wallet from the user to be verified or a certified video process.
Treezor provides you with a KYC Form upon starting your project. It indicates everything you need to provide for user verification.
# Process
Below is a high-level example of the KYC process for end-user onboarding:
The key steps are the following:
- You collect the necessary data based on your KYC Form (declarative data, documents, tax residence).
- You pre-review the documents to ensure proper quality before requesting a KYC review.
- Treezor manually verifies the user's identity (opens new window) and decides whether or not they are eligible to use Treezor services.
Best practice – Make sure you provide data of quality
Bad data quality may result in unnecessary back-and-forth with Treezor. The more accurate and vigilant you are when providing the necessary data when requesting a KYC / KYB review, the smoother the end-user experience.
# Provide user declarative data
User key information to provide (based on your KYC Form) is to be populated through the following objects:
- Users – Create or update your user with the relevant attributes
- Tax Residence – Declare the country of tax residency with a specific object (and add it to the corresponding User object)
# Provide documents
Treezor offers 2 ways for end users to upload documents:
The processes differ depending on the option you implement. Only once all the documents are properly updated can the KYC review by Treezor be requested. Learn more in the Documents section.
# Additional vigilance measures
Your KYC Form may indicate a SEPA Transfer as an additional vigilance measure, allowing Treezor to know that the User has already passed a verification process with a credit institution located in the European Economic Area (EEA).
This step consists of Users wiring money from their existing bank account to their new Treezor Wallet, and takes place between the upload of all the Documents and the request for a KYC review.
The User can wire money to their Wallet via its IBAN using one of the following methods:
Prerequisites – In order to make the initial transfer, the User must be created and
This money wiring will send you a payin.create webhook.
You must then wait for this Payin status (payinStatus) to be VALIDATED before requesting a KYC review.
The validation of the Payin confirms that this measure was passed.
Depending on the type of transfer, the validation of the Payin may be provided immediately upon creation of the Payin, or via the payin.update webhook within a few days.
Information – Transfer must be refunded if the User is not KYC-validated
You will need to get in touch with your Treezor Account Manager before being able to send a payinrefund.
# User KYC Levels (kycLevel)
The kycLevel represents our confidence in the assigned KYC Review status.
| Value | Plaintext | Description |
|---|---|---|
0 | NONE | No review occured yet for this User. |
1 | LIGHT | User has been accepted or refused for light reasons (invalidating this status is possible with new documents). |
2 | REGULAR | The User is KYC-validated. |
3 | STRONG | The User is KYC-validated. |
4 | REFUSED | Permanent refusal, further reviews will be denied. |
Services availability for the User differ depending on their KYC Level.
| Service | NONE | LIGHT | REGULAR | REFUSED |
|---|---|---|---|---|
| Create Cards |  |  | | |
| Pay by Card | | | | |
| Send funds | | | | |
| Receive funds | | | | |
| Request another KYC review | | | | |
Caution – When the User KYC level is LIGHT:
- It is your responsibility to lock the User's Cards
- Payouts are enabled only to allow the User to retrieve their funds before definitely closing their Wallet.
# User KYC Review status (kycReview)
The kycReview represent the current status of the user review by Treezor. It's for information purposes only, this value doesn't impact the services available to the User.
| Value | Plaintext | Additional information |
|---|---|---|
0 | NONE | No review yet. |
1 | PENDING | Review in progress. |
2 | VALIDATED | Review is done and the user is KYC-validated. |
3 | REFUSED | Review is done and the user is refused. |
4 | INVESTIGATING | |
5 | CLOSED | |
6 | REVIEW_OPEN | |
7 | REVIEW_PENDING |
Note – Each document receives its own review status
The User's review status is automatically deduced from all the documents individual review status.
# KYC Lifecycle
All Users start their KYC journey with kycLevel 0 (NONE) and kycReview 0 (NONE).
The most common scenario and lifecycles are described below.
# Straightforward validation
In this ideal process, the user produces decent quality and valid documents right away and doesn't exhibit counter indications to having a wallet.
| # | Description | user.kycLevel | user.kycReview |
|---|---|---|---|
| 0 | Initial state | 0 None | 0 None |
| 1 | ⬆️ User uploads all documents | 0 None | 0 None |
| 2 | ❔ You request a KYC Review | 0 None | 1 Pending |
| 3 | ✅ Treezor approves all documents | 2 Regular | 2 Validated |
Note – A validated Document cannot be replaced
If the user wishes to replace it, a new Document object has to be created, and a new KYC Review request has to be sent.
# Non-compliant documents
The user uploads all documents (1) but one is expired or non acceptable (3). The user loops back to the upload step (4) and provides an acceptable document that is validated by Treezor (5).
| # | Description | user.kycLevel | user.kycReview |
|---|---|---|---|
| 0 | Initial state | 0 None | 0 None |
| 1 | ⬆️ User uploads all documents | 0 None | 0 None |
| 2 | ❔ You request a KYC Review | 0 None | 1 Pending |
| 3 | ❌ Treezor rejects at least one document | 1, 2 or 3 Light, Regular or Strong | 3 Refused |
| 4 | ⬆️ User uploads new documents | 1, 2 or 3 Light, Regular or Strong | 3 Refused |
| 5 | ❔ You request a KYC Review | 0 None | 1 Pending |
| 6 | ✅ Treezor approves all documents | 2 Regular | 2 Validated |
Note – A refused Document cannot be replaced
If the user wishes to replace it, a new Document object has to be created, and a new KYC Review request has to be sent.
# Permanent refusal
The user uploads all documents (1), but analysis of the provided documents concluded that this user is not permitted to use Treezor's services (3).
This is a definitive refusal, all subsequent document uploads will be refused.
| # | Description | user.kycLevel | user.kycReview |
|---|---|---|---|
| 0 | Initial state | 0 None | 0 None |
| 1 | ⬆️ User uploads all documents | 0 None | 0 None |
| 2 | ❔ You request a KYC Review | 0 None | 1 Pending |
| 3 | ❌ Treezor refuses the User | 3 Refused | 3 Refused |
# Modifying a non-validated user
The user has uploaded documents but is not yet validated.
| # | Description | user.kycLevel | user.kycReview |
|---|---|---|---|
| 0 | Initial state | 0 None | 0 None |
| 1 | ⬆️ User uploads all documents | 0 None | 0 None |
| 2 | 🚮 User cancels a document | 0 None | 0 None |
| 3 | ⬆️ User uploads a new document | 0 None | 0 None |
| 4 | ❔ You request a KYC Review | 0 None | 1 Pending |
| 5 | ✅ Treezor approves all documents | 2 Regular | 2 Validated |
# Modifying an already validated user
The user has been validated previously, and decides to upload new documents.
During the upload of new documents, the user can still access his/her account.
| # | Description | user.kycLevel | user.kycReview |
|---|---|---|---|
| 0 | Already validated user | 2 Regular | 2 Validated |
| 1 | ⬆️ User uploads new documents | 2 Regular | 2 Validated |
| 2 | ❔ You request a KYC Review | 2 Regular | 1 Pending |
| 3 | ✅ Treezor approves the new documents | 2 Regular | 2 Validated |
# Straightforward, using KYC Liveness
In this ideal process, the user goes into KYC Liveness, and produces acceptable documents right away.
| # | Description | user.kycLevel | user.kycReview | kycliveness.kyc-status | kycliveness.score |
|---|---|---|---|---|---|
| 0 | Initial state | 0 None | 0 None | ||
| 1 | ❔ You request a KYC Liveness | 0 None | 0 None | initiated | -1 |
| 2 | 🔗 Treezor provides the KYC Liveness URL | 0 None | 0 None | initiated | -1 |
| 3 | 🔄 You redirect the End User to the KYC Liveness URL | 0 None | 0 None | initiated | -1 |
| 4 | ⬆️ The End User is guided into uploading the documents | 0 None | 0 None | initiated | -1 |
| 5 | 🔔 Treezor sends you a kycliveness.create webhook | 0 None | 0 None | processing | -1 |
| 6 | 🔔 Treezor sends you a kycliveness.update webhook | 0 None | 0 None | processed | 1 |
| 7 | ❔ You request a KYC Review | 0 None | 1 Pending | processed | 1 |
| 8 | 🔔 Treezor sends you document.create webhooks | 0 None | 1 Pending | processed | 1 |
| 9 | ✅ Treezor approves the documents | 2 Regular | 2 Validated | processed | 1 |
# Non-compliant documents, using KYC Liveness
The user completes the KYC Liveness process, but some documents are non-compliant. The user is refused by our KYC Liveness provider (Ubble).
| # | Description | user.kycLevel | user.kycReview | kycliveness.kyc-status | kycliveness.score |
|---|---|---|---|---|---|
| 0 | Initial state | 0 None | 0 None | ||
| 1 | ❔ You request a KYC Liveness | 0 None | 0 None | initiated | -1 |
| 2 | 🔗 Treezor provides the KYC Liveness URL | 0 None | 0 None | initiated | -1 |
| 3 | 🔄 You redirect the End User to the KYC Liveness URL | 0 None | 0 None | initiated | -1 |
| 4 | ⬆️ The End User is guided into uploading the documents | 0 None | 0 None | initiated | -1 |
| 5 | 🔔 Treezor sends you a kycliveness.create webhook | 0 None | 0 None | processing | -1 |
| 6 | 🔔 Treezor sends you a kycliveness.update webhook | 0 None | 0 None | processed | 0 |
# Compliant documents but refused User, using KYC Liveness
The user completes the KYC Liveness process and provide compliant documents. Nonetheless, Treezor refuses the User.
| # | Description | user.kycLevel | user.kycReview | kycliveness.kyc-status | kycliveness.score |
|---|---|---|---|---|---|
| 0 | Initial state | 0 None | 0 None | ||
| 1 | ❔ You request a KYC Liveness | 0 None | 0 None | initiated | -1 |
| 2 | 🔗 Treezor provides the KYC Liveness URL | 0 None | 0 None | initiated | -1 |
| 3 | 🔄 You redirect the End User to the KYC Liveness URL | 0 None | 0 None | initiated | -1 |
| 4 | ⬆️ The End User is guided into uploading the documents | 0 None | 0 None | initiated | -1 |
| 5 | 🔔 Treezor sends you a kycliveness.create webhook | 0 None | 0 None | processing | -1 |
| 6 | 🔔 Treezor sends you a kycliveness.update webhook | 0 None | 0 None | processed | 1 |
| 7 | ❔ You request a KYC Review | 0 None | 1 Pending | processed | 1 |
| 8 | 🔔 Treezor sends you document.create webhooks | 0 None | 1 Pending | processed | 1 |
| 9 | ❌ Treezor refuses the documents | 1 Light | 3 Refused | processed | 1 |
# Endpoints
| Endpoint | Description | Scope |
|---|---|---|
/v1/users/{userId}/Kycreview | Initiate the user KYC review process | read_write |
/v1/users/{userId}/Kycliveness | Initiate the user Live verification process | read_write |
/v1/users/{userId}/Kycliveness | Upload the documents once the Live verification is completed. | read_write |
/v1/documents | Create a document | read_write |
/v1/documents | Search for documents | read_only |
/v1/documents/{documentId} | Retrieve a specific document based on its id | read_only |
/v1/documents/{documentId} | Update a document name | read_write |
/v1/documents/{documentId} | Delete a document | read_write |
/v1/documents/{documentId}/download | Retrieve a document download URL | read_only |
/v1/taxResidences | Create a Tax Residence | read_write |
/v1/taxResidences | Search for Tax Residences | read_only |
/v1/taxResidences/{taxResidenceId} | Update a Tax Residence | read_write |
/v1/taxResidences/{taxResidenceId} | Retrieve a Tax Residence based on its id | read_only |
/v1/taxResidences/{taxResidenceId} | Delete a Tax Residence | read_write |
← Support Users Events →