User Module

The User module contains structures and processes for user data management, the KYC-process and verification processes for various user data, such as email address, phone-number, address, date of birth, nation code etc.

  • user.api - contains the internal API for the User module
  • user.impl - contains the implementation for the User module

Entities

User

The User represents a customer legal entity that is the legal contract partner for a Subsidiary. A user is also typically the owner of a wallet. A user has the following attributes which can be stored in the database:

  • ID
  • birth country
  • birth place
  • citizenship
  • creation datetime
  • date of birth
  • display name
  • first name
  • gender
  • invited by
  • IP address
  • is on watch list flag
  • language
  • last name
  • nation code
  • occupation
  • personal number
  • primary address ID
  • primary email ID
  • primary phone ID
  • registration source
  • source of income
  • status
  • subsidiary ID
  • verified address flag
  • verified bank account flag
  • verified birth place flag
  • verified citizenship flag
  • verified date of birth flag
  • verified email flag
  • verified gender flag
  • verified identification document flag
  • verified name flag
  • verified nation code flag
  • verified personal number flag
  • verified phone flag
  • verification level

Only a couple of the fields are mandatory (non-nullable in the database), e.g. creation datetime, language, nation code, status, subsidiary ID. Subsidiary ID and nation code are the most important, because important configuration parameters for business processes like KYC verification processes are bound to these fields.

Identifier

Every User can have 1 to n Identifiers which can be used to authenticate the user.

An Identifier has the following attributes which can be stored in the database:

  • identifier (value of the identifier)
  • scope (a reference to the identifier scope)
  • creation datetime
  • identifier type (e.g. email or phone)
  • user ID (a reference to the user)

Identifier scope

Every Identifier belongs to an Identifier scope and the Identifier must be unique within this scope.

An Identifier scope has the following attributes which can be stored in the database:

  • ID
  • country
  • qualifier (free text field allowing you to refine the scope)
  • scope key
  • subsidiary ID (a reference to a subsidiary)
  • identifier type (e.g. email or phone)

Email

Every User can have 1 to n Emails which can be used for for communication purposes and in the KYC processes (see description for the KYC processes below). One email is always marked as primary (standard), this email is used by default for sending emails to the user. A user can have one or more verified email addresses. As soon as at least one email address is verified, the verified email flag of the user is also turned on.

An Email has the following attributes which can be stored in the database:

  • ID
  • creation datetime
  • display email address (as entered by the user)
  • email address (normalized)
  • standard flag
  • status (e.g. Active)
  • newsletter subscription status (Subscribed/Unsubscribed)
  • verified flag
  • user ID (reference to a user)

Phone

Every User can have 1 to n Phones which can be used for communication purposes and in the KYC processes (see description for the KYC processes below). One phone is always marked as primary (standard), this phone is used by default for sending SMSs to the user. A user can have one or more verified phones. As soon as at least one phone is verified, the verified phone flag of the user is also turned on.

A Phone has the following attributes which can be stored in the database:

  • ID
  • creation datetime
  • display phone number (as entered by the user)
  • phone number (normalized)
  • standard flag
  • status (e.g.  Active)
  • verified flag
  • user ID (a reference to the user)

Address

Every User can have 1 to n Addresses which can be used for communication purposes and in the KYC processes (see description for the KYC processes below). One address is always marked as primary (standard), this address should be used by default for example for sending paper letters to the user. A user can have one or more verified addresses. As soon as at least one address is verified, the verified address flag of the user is also turned on.

An Address has the following attributes which can be stored in the database:

  • creation date time
  • first name (of the recipient, might be different from the user’s first name)
  • last name (of the recipient, might be different from the user’s last name)
  • display name (of the recipient, might be different from the user’s display name)
  • address line 1
  • house number
  • address line 2
  • district
  • city
  • province
  • country
  • zip
  • standard flag
  • verified flag
  • type (SHIPPING / BILLING / STANDARD)
  • user ID (reference to the user)

IdDocument

Every User can have 1 to n IdDocuments which he can upload in order to apply for KYC verifications. Usually these documents are copies of government-issued identification cards or passports for proof of identity and recent utility bills for proof of residence.

An IdDocument has the following attributes which can be stored in the database:

  • ID
  • creation datetime
  • file name (generated by the system)
  • file path
  • file content type
  • file size bytes
  • original file name
  • status (Accepted/Created/Rejected/Revoked)
  • status change datetime
  • status text
  • qualifier (free text field e.g. identification document, utility bill)
  • verified flag
  • expiration date (where applicable)
  • purpose
  • user ID (reference to the user)

InternalDocument

Every User can have 1 to n InternalDocuments which an admin can upload for the user. These documents cannot be used in the KYC verification processes of the user data and are stored only in order to keep the communication history or to store additional information about the user.

An InternalDocument has the following attributes which can be stored in the database:

  • ID
  • creation datetime
  • comment (employee/admin comment)
  • file content type,
  • file name (generated by the system)
  • file path
  • file size bytes
  • original file name
  • qualifier (free text field)
  • status (Created/Deleted)
  • status datetime
  • user ID (reference to the user)

VerificationHistory

For documentation and auditability purposes, a history of data verification actions per User  is kept in the special table where the following attributes can be stored:

  • ID
  • user attribute (e.g. EMAIL / PHONE / NATIONCODE / NAME and so on)
  • creation datetime
  • verification item id (ID of the IdDocument which was used for verification if applicable)
  • verfiied item ID (database ID of the verified item, e.g. address, email or phone if applicable)
  • verified value (verified value as string or JSON string)
  • user ID (reference to the user)

UserDataUpdate

For documentation and auditability purposes, a history of data updates per User  is kept in the special table where the following attributes can be stored:

  • ID
  • creation datetime
  • item ID (database ID of the updated item, e.g address, email, phone if applicable)
  • status (created, canceled, verification_needed, applied)
  • update action (add, update, delete)
  • update display value (value as entered by the user)
  • update time
  • update type
  • update value (normalized value)
  • user ID (reference to the user)

Configuration

The user module also provides a com.trimplement.wallet.server.user.impl.product.ProductConfiguration to customize certain behaviors. Instances are accessed via the com.trimplement.wallet.server.user.impl.product.ProductConfigurationProvider.getProductConfiguration(long subsidiaryId, CountryCode country) which allows to provide a specific configuration per subsidiary and country.

Example configuration possibilities are:

  • Minimum/maximum allowed number of stored addresses, phone numbers, email addresses, ID documents per user
  • User data update configuration (e.g. whether already verified data can be overwritten, whether verification is needed when a verified value is overwritten, whether user data is allowed to be deleted from the database or only marked as ‘deleted’)
  • Which user data is required and verifiable per KYC verification level
  • Which authentication roles are allowed to be assigned to an user (e.g. to prevent accidentally giving a user the SYSTEM role)
  • Minimum/maximum user age acceptable in the system
  • Allow/prohibit duplicate phone numbers
  • Allow/prohibit specific file content types for document upload
  • The supported user verification levels (for KYC)
  • The supported emails and SMS
  • The supported email and SMS languages
  • Retry delay configuration for SMS and email sending
  • Allow/prohibit using an unverified email as primary email address
  • Enable using of every verified email as identifier
  • Allow/prohibit deletion of an user identifier upon user termination (make them available again for another user or not)
  • Allow/prohibit recipient names in user’s billing addresses different from user’s name

Please note that configuration possibilities may change over time so the best way to check currently available configuration options would be to check the source code of com.trimplement.wallet.server.user.impl.product.ProductConfiguration.

Communication with the user

Emails

The User module can send different verification and notification emails to a user.

The User module only triggers the email sending and stores only the data needed for a concrete email in the database. The com.trimplement.wallet.server.common.email.EmailSendService interface from the Common module must be implemented to provide the actual email templating and sending, e.g. via a direct SMTP implementation, or by integrating an external service.

CoreWallet provides default implementation of email send service via Mailgun, if another mail sending provider is wanted, it needs to be implemented on the Product level.

SMS

The User module can send different verification and notification SMS.

The User module only triggers the SMS sending and stores only the data needed for a concrete SMS in the database. The com.trimplement.wallet.server.common.sms.SmsSendService interface from the Common module must be implemented to provide the actual SMS-templating and sending, e.g. by integrating an external service.

CoreWallet provides default implementations of an SMS send service via Twilio and SureSMS, if another SMS sending provider is wanted, it needs to be implemented on the Product level.

KYC (Know Your Customer) Processes

Know your customer (KYC) is the process of a business identifying and verifying the identity of its clients. The concrete KYC requirements (mandatory user data, acceptable verification process, applicable limits) are defined through the bank and anti-money laundering regulations which may be different from country to country.

The User module of the CoreWallet provides basic implementations of common steps of the widespread KYC procedures. It supports:

  • Email verification
  • Phone verification
  • Personal user data verification / ID documents upload

Please note that payment instrument (credit card or bank account) verification is not a part of the User module, but a part of the Wallet module, because payment instruments are associated with a wallet and not with a user. Nonetheless, the information about the successful bank account verification (verified bank account flag mentioned above) is stored with the user as changing of the value of this flag may trigger a change of the KYC level of the user.

Email verification

The email verification process is typically started right after the user registration. The user receives an email with a link containing a verification token to click on, or the verification token itself is to be entered on the Product site. The email can be resent. There is a configurable retry limit of allowed verification attempts. The validity of the verification token is also configurable.

Phone verification

The phone verification process is similar to the email verification process. It typically starts right after the phone number is added to the user data. The user receives an SMS containing the verification token to be entered on the Product site. The SMS can be resent. There is a configurable retry limit of allowed verification attempts. The validity of the verification token is also configurable.

Personal user data verification / ID documents upload

The personal data verification process supported in the CoreWallet by default is semi-automatic:

An user can upload a (limited per configuration) number of ID documents. Allowed document filename extensions are configurable in the Common module, in the file transmission service. Typically, personal ID document or passport copies and utility bills are required for a manual KYC verification.

An administrator can review these uploaded documents in the AdminUI and accept or reject them. When accepting a document, an administrator can mark different personal user data attributes as verified (e.g. birth place, date of birth, name, nationality, address). When rejecting a document, an administrator can enter a reason for rejection. This information will be sent to the user in an email, so that he can upload a new ID document.

When a document is accepted and user data fields are marked as verified, according database entities and user attributes are updated (see above).

KYC levels

Depending on the local bank and anti-money-laundering regulations, different user data is required and must be verified in order for the user to achieve the next KYC level. A user’s KYC level is used to apply different system limits, e.g. funding or withdrawal amount limits or to determine allowed user actions like triggering a P2P transaction or making a purchase.

Automatic update

When user data is verified, the system triggers a set of actions. One important action is triggering the KYC user level state machine. The system checks user data verification configuration stored in the database (what fields are required and must be verified per KYC level) and updates the user’s KYC level automatically if applicable.

Manual update

If an automatic update failed (e.g. if the user data verification configuration was incorrect and fixed later) or in case of any other reason, an administrator can update a user’s KYC level manually in the AdminUI.

Limits

As mentioned above user’s KYC level determines applicable financial transaction limits. Limits configuration is part of the Wallet module. See

com.trimplement.wallet.server.wallet.api.limit.LimitService for more detail.

Permitted user actions

As mentioned above user’s KYC level determines allowed user actions. Permitted actions configuration is part of the Wallet module. See com.trimplement.wallet.server.wallet.api.permission.ActionPermissionConfigurationService for more detail.