Abstract

This document specifies the Merchant Schema for ingesting merchant data into CDLX systems to enable processing and tracking of merchant information. Merchant data is provided daily in JSON format, including all active, new, updated, unchanged, and deleted merchants as categorized by status.

The schema defines a file header with metadata and a detailed structure for each merchant record, covering identification, categorization, payment channels, contact details, store locations, and payment processing information. The schema supports hierarchical merchant relationships, multiple store locations per merchant, and extensive attributes for store payment processing and contact information.

The goal is to standardize the ingestion of comprehensive merchant data for downstream processing within CDLX systems.

Merchant Schema

Purpose: To ingest merchant data into CDLX systems for processing and tracking.

File Name: <Partner_Name>MerchantsCCYYMMDD

File Type: JSON

File Frequency: Once a day (if there are new/updated/deleted merchants)

File Features

Includes all active merchants categorized as NEW, UPDATED, NO-CHANGE.
Deleted merchants appear under the status DELETED.
Updated records may contain multiple attribute changes.

Header

Field Name	Data Type	Note
fileDescription	String
fileCreationDate	String	YYYY-MM-DD
merchantRecordCount	Numeric	The number of merchant records included in the file

MerchantRecord

Field Name	Data Type	Required	Note
merchantStatus	String	Yes for SFTP, No for REST	NEW/DELETED/UPDATED/UPSERT/NO-CHANGE
merchantId	String	Yes	Partner provided merchant identifier
merchantName	String	Yes	Registered name of the merchant or brand
parentMerchantId	String	No	Any Parent of this merchant
merchantCategoryCode	String	No	ISO 18245 4-digit MCC code
merchantSubCategories [*].categoryType	String	No	Example: Cuisine
merchantSubCategories [*].categoryItems	Array of String	No	Example: ["Continental", "American"] No special characters
paymentChannels	String []	Yes	Indicates if this merchant ID accepts payments online or instore
paymentSubChannels	String []	No	Indicates the payment sub-channel of the merchant (Example "PayAtPump", "Convenience"). PayAtPump - For gas station offers, indicates that the purchase can/must be made at the fuel pump. Convenience - Valid for purchases within or at the physical convenience store location.
merchantUrl	String	No	Merchant Website URL
merchantApps	String []	No	List of Online Apps used by Merchant
stores [*].storeId	String	Yes	The external partner provided store identifier
stores [*].storeName	String	Yes	Name of the store
stores [*].locatedIn	String	No	Business or venue the merchant is inside example: “SFO Airport Terminal 2” or “Pen Station” or “Walmart” or “Target” or “Westfield Mall”
stores [*].address1	String	Yes	Street Address
stores [*].address2	String	No	Street Address
stores [*].city	String	Yes
stores [*].state	String	Yes
stores [*].postalCode	String	Yes
stores [*].countryCode	String	Yes	2 Character country code - ISO 3166-1 alpha-2
stores [*].latitude	String	No	The latitude coordinates of the merchant store location Example: "37.7661"
stores [*].longitude	String	No	The longitude coordinates of the merchant store location Example: "-122.3958"
stores [*].storePhoneNumbers	String []	No	List of phone number of the store
stores [*].storeEmails	String []	No	List of business email of the store
stores [*].storeUrl	String	No	Store Website URL
stores [*].processorMidChangedFlag	String	Yes	Y=Yes, N=No
stores [*].processorMidRecords	JSON Array	Yes
stores [].processorMidRecords [].paymentNetwork	String	Yes	“Visa”, “MasterCard”, “AmericanExpress”, “Discover”
stores [].processorMidRecords [].processors	JSON Array	Yes
stores [].processorMidRecords [].processors [*].processorName	String	Yes	Name of the processor Clover, Square, Worldpay, Fiservm Elavon, First Data etc. When not available use “UNKNOWN”
stores [].processorMidRecords [].processors [*].processorId	String	No	Any Id assigned to the Processor