Merchants File - Envisso Integration Hub

Overview

Context — The merchant details should contain details of all active merchants within your platform. File Type — CSV File Name — <company_name>_merchants_YYYYMMDDHHmmSS

Example: <company_name>_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. 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. Example for Singapore: `UEN`.
`registered_country`	country	Mandatory	Country where the merchant is legally registered — 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. 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 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 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.