> ## Documentation Index
> Fetch the complete documentation index at: https://docs.envisso.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Merchants File
> Specification for the daily merchants file delivered to Envisso.
Merchants file template with column headers and descriptions.
## Overview
**Context** — The merchant details should contain details of all active merchants within your platform.
**File Type** — CSV
**File Name** — `_merchants_YYYYMMDDHHmmSS`
* Example: `_merchants_20221110233030`
* `company_name` = your company's name
**Frequency** — Daily
* Files should contain records for:
* New merchants to be onboarded.
* Existing merchants to be updated. For example if a merchant has changed their website URL or registered address.
* Existing merchants to be offboarded via the `merchant_status` column.
* If there are no merchants being added or removed, the daily file can contain a single line with the column headers and no data records below.
## Data Columns
The following table provides the column definitions for the merchant data. Each row represents a merchant as a legal entity, as it is registered with the relevant government authority, rather than individual merchant accounts as defined by Payment Service Providers (PSPs).
| Column | Type | Required | Description |
| --------------------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `environment` | enum | Mandatory | Environment to which the merchant belongs. Allowed: `PRODUCTION`, `TESTING`. Files should only contain records from a single environment. Invalid values reject the record. |
| `merchant_status` | enum | Mandatory | Status of the merchant in the PSP system. Allowed: `LIVE`, `DEACTIVATED`. `LIVE` merchants are actively monitored; `DEACTIVATED` merchants have no further aggregation, enrichment, or alerts, and don't count toward the PSP bill. |
| `merchant_registration_id` | string | Mandatory | The legal registration ID of the merchant, assigned by the relevant government authority in the merchant's registered country. See [Merchant Registration ID Types](/data-dictionaries/merchant-registration-id-types). Example for Singapore: `201912345H`. |
| `registration_id_type` | enum | Mandatory | Type of registration ID based on the country where the merchant is registered. See [Merchant Registration ID Types](/data-dictionaries/merchant-registration-id-types). Example for Singapore: `UEN`. |
| `registered_country` | country | Mandatory | Country where the merchant is legally registered — [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166) alpha-2. Example: `SG`. |
| `internal_merchant_ids` | string | Optional | Pipe-separated (`\|`) list of internal merchant IDs associated with this merchant. Defines a one-to-many relationship between the legal entity and its linked accounts. IDs longer than 64 characters will be truncated. Example: `398-347-598\|984-327-985`. |
| `company_registration_date` | date | Mandatory | Official registration date of the merchant's company — [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Example: `2024-01-30`. |
| `onboarding_date` | date | Optional | Onboarding date of the merchant in the PSP system — ISO 8601. Example: `2024-01-30`. |
| `website_url` | url | Mandatory | Merchant's website URL. Protocol (`http://` / `https://`) can be omitted. Example: `www.timstiles.com`. |
| `timezone` | timezone | Mandatory | Timezone used for bucketing transactions and display in the Risk Console — [tz database](https://www.iana.org/time-zones) name. Invalid values fall back to an account default. Example: `Asia/Singapore`. |
| `trading_currency` | currency | Mandatory | Currency in which the merchant is trading — [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) alpha-3. Example: `SGD`. |
| `estimated_annual_tpv` | integer | Mandatory | Estimated annual Total Payment Volume (TPV) for this merchant, in the main unit of `trading_currency`, no thousand delimiters, no decimals. Required when `protect_enrolment` is `TRUE`; may be blank otherwise. Defaults to zero if missing. Example: `8000000`. |
| `legal_name` | string | Mandatory | Merchant's legal name as registered with the relevant government authority. Example: `ABC Trading Ltd.`. |
| `registered_address_line_1` | string | Optional | First line of the merchant's legally registered address. Typically a street address or PO Box. Example: `100 High Street`. |
| `registered_address_line_2` | string | Optional | Second line — suite or apartment number. Example: `Suite 300`. |
| `registered_city` | string | Optional | City where the merchant is legally registered. Example: `London`. |
| `registered_postal_code` | string | Optional | Postal code or ZIP code of the legally registered address. Example: `238884`. |
| `protect_enrolment` | boolean | Optional | Whether the merchant is enrolled in the Envisso Protect insurance programme. Allowed: `TRUE`, `FALSE`. |
| `enrolled_mccs` | string | Mandatory | Space-separated list of 4-digit MCCs (ISO 18245) currently enrolled in Envisso Protect. Required when `protect_enrolment` is `TRUE`; may be blank otherwise. Example: `5251 5714`. |
| `value_at_risk` | integer | Mandatory | Maximum loss the PSP could suffer if the merchant defaults, in the main unit of `trading_currency`, no thousand delimiters, no decimals. Required when `protect_enrolment` is `TRUE`; may be blank otherwise. Previously known as `exposure`. Example: `135000`. |
| `delivery_days` | integer | Optional | Average number of calendar days between when the merchant receives payment and when goods or services are delivered. `0` for immediate delivery (e.g. digital goods). Example: `14`. |
Invalid values for any mandatory column will cause the record to be rejected and it must be re-sent in a subsequent file.