## Definitions

1. **Data Provider** - A Factiiv Data Provider furnishes historical transaction data to Factiiv via a CSV file.
2. **Unclaimed business** - A business entered into factiiv by an admin, user or data provider which does not have a profile/account that owns the business in factiiv.
3. **Chargeback** - A chargeback is when someone pays anopther person via credit card and later contacts their credit card company to claim the charge was fraudulent, or the product/service they paid for was never received. When this occurs it can hurt a business in multiple ways and damage their reputation and standing with their credit card processer.

## Summary

We will be adding a new subdomain (or just a new section of the credit subdomain, this is to the discretion of the developers) to factiiv for Data Providers to log in using a supplied password, upload data, review uploaded data and see statistics on uploaded data.

Data Providers will be able to upload 3 different types of data -- trades, trade activity items and chargebacks. All information uploaded by Data Providers will need to be approved by the business being reported against just like with any other user-to-user reported trade.

Data Providers will be provided with the CSV template for download which corresponds to the data type they are uploading and the formatting of the CSV should be validated by the backend before uploading data into the database.

Data Providers will be able to see all of the CSV files they have uploaded, how many new trades, activity items, and chargebacks they have provided to factiiv and how many new factiiv users have been created as a result of their uploaded data.

## Domain structure

On the provider subdomain https://provider.factiiv.io or somewhere on the existing credit subdomain like https://credit.factiiv.io/provider/login, the first page seen by a provider should be the login page `/login` (noted by a star in the diagram) protected routes have a gold background in the diagram.

## Registration

The Data Provider Portal will have closed registration done by invite only. Factiiv admins will be the only ones to create a data provider, this is triggered after a provider interacts with the [become a partner](https://factiiv.io/become-a-partner/) form on the front end site.

Once created in the backend an email should be sent to the new user's designated email address with a temporary password and a link to the First time login page where they will enter their provided password, enter a new password and then be logged in.

## Admin Create User

The creation of data provider users should be done in the main factiiv superadmin dashboard. It has been included in the [outline page for data providers](https://factiiv-design.web.app/provider/outline/) on the design demo site and the link to this new create provider page has been added to the [superadmin dashboard sidebar](https://factiiv-design.web.app/admin/) just below the create admin link.

## Login `/login`

Design: https://factiiv-design.web.app/provider/login

A simple login form with email and password and a reset password link which sends an email with reset instructions and shows the user a reset password notice design for that is here: https://factiiv-design.web.app/provider/reset-notice

After logging in the user will be shown the upload portal.

## Upload portal `/`

Design: https://factiiv-design.web.app/provider/

Lives on the root of the provider subdomain.

Interface to allow download of CSV templates and upload of completed CSV files.

**Split screen with 2 options**: Upload Trades/Activity -or- Upload Chargeback activity.

Beneath both actions there will be a download button for the corresponding CSV template.

### Upload workflow

The most important part of the data provider portal is that it will automate the uploading and sorting of data by data providers and ensure the formatting of data is correct and that any exact matches for businesses existing within factiiv are attributed correctly.

The UI flow for this process can be seen by uploading a CSV in the design demo at https://factiiv-design.web.app/provider/ and clicking the review button.

#### 1. Catalogue

Each CSV uploaded will be given a Reference ID number by which both data providers and factiiv admins can look up the file by.

#### 2. Validation

When a CSV is uploaded for review by a data provider our backend should perform initial validation according to the template. A function should iterate over each line in the uploaded CSV and ensure the following:

1. **The headers of the uploaded CSV match the corresponding template** The CSV templates can be found here (need to put CSV files in Drive and link here). -- [name=JHethDev]
2. **All columns are filled in for all lines where data is present**
3. **The proper data type is entered for fields where validation is necessary**

**Required fields for Trades/Activity line items: REPORT DATE (A), DATE OPENED (B) and TAX ID/SSN (M)**

> - Both REPORT DATE and DATE OPENED should be provided in the format of `YYYYMMDD`
> - TAX ID/SSN is required to have 9 numbers but can come in the format of either `123-45-6789` or `12-3456789` an example regex pattern to match only these two conditions would be [`/^(?:\d{2}-\d{7}|\d{3}-\d{2}-\d{4})$/`](https://regexr.com/7id2u)

**Required fields for Chargeback line items: (need chargeback data template)**

> place notes for chargeback field validation here.
> [name=JHethDev]

If any errors are present in the uploaded CSV then the file should be rejected and the user should get a detailed error report. For example if a single line in the CSV file does not have a properly formatted TAX ID/SSN then the user should be provided with the row number and column letter where the error exists and the following message "incorrectly formatted TAX ID/SSN on row: 32, Column M. Please provide either xx-xxxxxxx or xxx-xx-xxx format for this row.".

Design for the error state can be seen here: https://factiiv-design.web.app/provider/upload-error

#### 3. Confirmation

After the uploaded CSV has gone through all of the necessary checks the user should be shown the output in a table on the webpage this can be seen in the second step of the

They can look through the data they provided to ensure all of the output looks correct.

Below the table will be an "upload" button.

#### 4. Attribution

Once the data is sent through to factiiv the backend should perform some functions.

The first function is to add the data provider to each piece of data.

Next is to check whether the **Account number** provided in the row of the CSV matches an account number used by this data provider before.

If there is already a trade provided by the same data provider using the same account number (not the ID assigned by factiiv, the actual trade number as it exists in the data provider's records) then first a check should be done to make sure it does not exactly match any entries already provided for this account number, if it is a duplicate it should be marked as duplicate data and ignored from the statistics. If it is not duplicate data then it should be entered as trade activity for the existing trade in factiiv as opposed to a new trade.

All remaining rows on the CSV should be processed as follows:

1. Find all rows in the CSV relevant to existing businesses and enter the trade or chargeback data as it's proper type in the user's history (they can still approve or deny these trades/chargebacks)
a. This should be done using the business name, city, state, zip code and tax id number if provided.
b. Any near matches should be flagged for manual review by an admin, for instance if the business name and address matches but a different tax id is provided or if the tax id matches a business in the system but the name does not.
2. Create "unclaimed" businesses in the system (businesses that have no owner/profile associated with them).
3. Attribute all trades/activity/chargebacks to either an existing or unclaimed business, there should be none at this point that are not attributed or flagged for attribution by an admin.

#### Upload

Once all trades/activity or chargebacks are properly attributed or flagged for admin attribution the data should be entered into the database.

## History (search and download past files) `/history`

Design: https://factiiv-design.web.app/provider/history

A sortable, searchable, filterable table showing all of the CSV files the user has uploaded.

**Relevant data to show in table**:

- Reference ID
- Date of upload
- Number of lines in CSV
- Type (Trades/activity or chargebacks)

**Sort options**:

- Date uploaded (Oldest to Newset)
- Date uploaded (Newest to Oldest)
- Line count (Largest to Smallest)
- Line count (Smallest to Largest)

**Search criteria**

- Reference ID

Empty history state can be seen here: https://factiiv-design.web.app/provider/history-empty

## Stats `/stats`

Design: https://factiiv-design.web.app/provider/stats

A data breakdown showing the cumulative result of past CSV uploads.

The main area at the top of the page will show the following data points:

- Number of CSV files uploaded
- Line count of CSV files uploaded
- Data approval rate percentage
- How many factiiv businesses have been created as a result of the user's uploads
- Data provider rank (based on accept to reject ratio and total data uploaded **need calculations**)

below that will be a breakdown of the three main data types, accepted, rejected, and not reviewed by users.

Empty stats page state can be seen here: https://factiiv-design.web.app/provider/stats-empty