Skip to main content

Download CSV template

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 — <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).
ColumnTypeRequiredDescription
environmentenumMandatoryEnvironment to which the merchant belongs. Allowed: PRODUCTION, TESTING. Files should only contain records from a single environment. Invalid values reject the record.
merchant_statusenumMandatoryStatus 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_idstringMandatoryThe 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_typeenumMandatoryType of registration ID based on the country where the merchant is registered. See Merchant Registration ID Types. Example for Singapore: UEN.
registered_countrycountryMandatoryCountry where the merchant is legally registered — ISO 3166 alpha-2. Example: SG.
internal_merchant_idsstringOptionalPipe-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_datedateMandatoryOfficial registration date of the merchant’s company — ISO 8601. Example: 2024-01-30.
onboarding_datedateOptionalOnboarding date of the merchant in the PSP system — ISO 8601. Example: 2024-01-30.
website_urlurlMandatoryMerchant’s website URL. Protocol (http:// / https://) can be omitted. Example: www.timstiles.com.
timezonetimezoneMandatoryTimezone 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_currencycurrencyMandatoryCurrency in which the merchant is trading — ISO 4217 alpha-3. Example: SGD.
estimated_annual_tpvintegerMandatoryEstimated 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_namestringMandatoryMerchant’s legal name as registered with the relevant government authority. Example: ABC Trading Ltd..
registered_address_line_1stringOptionalFirst line of the merchant’s legally registered address. Typically a street address or PO Box. Example: 100 High Street.
registered_address_line_2stringOptionalSecond line — suite or apartment number. Example: Suite 300.
registered_citystringOptionalCity where the merchant is legally registered. Example: London.
registered_postal_codestringOptionalPostal code or ZIP code of the legally registered address. Example: 238884.
protect_enrolmentbooleanOptionalWhether the merchant is enrolled in the Envisso Protect insurance programme. Allowed: TRUE, FALSE.
enrolled_mccsstringMandatorySpace-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_riskintegerMandatoryMaximum 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_daysintegerOptionalAverage 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.