SFTP Option

Abstract

This document outlines the standardized requirements and procedures for partners to upload Merchant and Merchant Identification (MID) files via SFTP for ingestion. The file must be in JSON format, named using the partner's identifier and the file creation date, and uploaded daily if there are any new, updated, or deleted merchant records.

Each file must contain a full list of merchants (active and deleted), organized by their status—NEW, UPDATED, UPSERT, NO-CHANGE, or DELETED—using a mandatory "merchantStatus" field for each record. The upload process includes strict guidelines on file naming, overwriting, and the inclusion of a header record with metadata.

Partners must ensure data consistency by maintaining merchant identifiers across uploads, and no upload is needed if there are no changes since the last file. Proper JSON formatting is required to prevent processing errors.

How It Works

  • Standardized schema format for getting the Merchant + MID file for ingestion from the Partner.
  • Partners use an SFTP URL to upload files.

Recommendations on how to call

  • File Type: JavaScript Object Notation (JSON)
  • File Name: <Partner_Name>MerchantsCCYYMMDD.json
    • <Partner_Name> → Your unique identifier as a partner.
    • CCYYMMDD → The date of file creation in 4-digit year, 2-digit month, and 2-digit day format.
  • File Frequency: Once a day (if there are new/updated/deleted merchants)
  • File Upload Requirements
    • Partners must provide a full dump of all merchants, including corresponding metadata, with each file upload.
  • File Features
    • All files must include a header record
    • All Active merchants will appear in the file broken down by status – NEW/UPDATED/UPSERT/NO-CHANGE.
    • All Deleted Merchants for the day will appear under the file under status – DELETED
    • An Updated Merchant Record can have one or more updates to its attributes
  • File Overwrite Policy
    • If a file with the same name already exists, it will be replaced by the newly uploaded file.
  • When Is a File Upload Required?
    • A new file must be uploaded if there are new, updated, or deleted merchants.
    • File upload is not required if there are no changes (i.e., no merchants were added, updated, or removed).
      • CDLX will continue using the previously uploaded merchant list until a new file is provided.
  • Merchant Status Field
    • Every merchant entry in the JSON file must include a "merchantStatus" field to indicate changes compared to the previously uploaded file.
    • The "merchantStatus" field can have one of the following values:
      • NEW - A new merchant has been added.
      • UPDATED - An existing merchant’s information has changed.
      • UPSERT - The merchant is new or updated.
      • DELETED - The merchant should be removed from the list.
      • NO-CHANGE - The merchant’s data remains the same as in the previous upload.
  • Additional Guidelines
    • Ensure files are properly formatted in JSON to avoid processing errors.
    • Retain the same merchant identifiers (merchantId) across file uploads for consistency in tracking changes.

Sample File Content

{
    "headerRecord":
    {
        "fileDescription": "Merchants",
        "fileCreationDate": "2025-01-27",
        "merchantRecordCount": 4
    },
    "merchantRecords":
    [
        {
            "merchantStatus": "NEW",
            "merchantId": "12345",
            "merchantName": "Luigi's Pizza",
            "merchantCategoryCode": "5812",
            "merchantUrl": "www.abc.com",
            "merchantSubCategories":
            [
                {
                    "categoryType": "cuisine",
                    "categoryItems":
                    [
                        "Continental",
                        "American"
                    ]
                }
            ],
            "paymentChannels":
            [
                "instore"
            ],
            "stores":
            [
                {
                    "storeId": "1001",
                    "storeName": "Luigi's Pizza Main St",
                    "storeUrl": "www.abc.com/mainSt",
                    "address1": "123 Main St",
                    "city": "NEWTOWN",
                    "state": "CT",
                    "postalcode": "06470",
                    "countryCode": "US",
                    "latitude": "37.7661",
                    "longitude": "-122.3958",
                    "storePhoneNumbers":
                    [
                        "+18881234567"
                    ],
                    "storeEmails":
                    [
                        "xyz@abc.vom"
                    ],
                    "processorMidChangedFlag": "N",
                    "processorMidRecords":
                    [
                        {
                            "paymentNetwork": "AmericanExpress",
                            "processors":
                            [
                                {
                                    "processorName": "AmericanExpress",
                                    "amexMids":
                                    [
                                        {
                                            "seNumber": "1234567890"
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "paymentNetwork": "MasterCard",
                            "processors":
                            [
                                {
                                    "processorName": "Elavon",
                                    "mcAuthMids":
                                    [
                                        {
                                            "mcAuthLocationId": "111222333",
                                            "mcAuthAcquiringMid": "444445555566666",
                                            "mcAuthICA": "012222"
                                        }
                                    ],
                                    "mcClearingMids":
                                    [
                                        {
                                            "mcClearingLocationId": "111222333",
                                            "mcClearingAcquiringMid": "444445555566666",
                                            "mcClearingICA": "12222"
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "paymentNetwork": "Visa",
                            "processors":
                            [
                                {
                                    "processorName": "Fiserv",
                                    "processorId": "FISV123",
                                    "visaMids":
                                    [
                                        {
                                            "vmid": "12345678",
                                            "vsid": "11444455"
                                        }
                                    ]
                                },
                                {
                                    "processorName": "Worldpay",
                                    "processorId": "WORLDPAY99",
                                    "visaMids":
                                    [
                                        {
                                            "vmid": "87654321",
                                            "vsid": "99887766"
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "paymentNetwork": "Discover",
                            "processors":
                            [
                                {
                                    "processorName": "Discover",
                                    "discoverMids":
                                    [
                                        {
                                            "discover": "4445040865057"
                                        },
                                        {
                                            "discover": "4445068632298"
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "merchantStatus": "UPDATED",
            "merchantId": "56789",
            "merchantName": "Thai 55",
            "merchantCategoryCode": "5812",
            "paymentChannels":
            [
                "instore"
            ],
            "stores":
            [
                {
                    "storeId": "2001",
                    "storeName": "Thai 55",
                    "address1": "5555 Highland Rd",
                    "city": "PRAIRIE VILLAGE",
                    "state": "KS",
                    "postalcode": "66208",
                    "countryCode": "US",
                    "processorMidChangedFlag": "Y",
                    "processorMidRecords":
                    [
                        {
                            "paymentNetwork": "AmericanExpress",
                            "processors":
                            [
                                {
                                    "processorName": "AmericanExpress",
                                    "amexMids":
                                    [
                                        {
                                            "seNumber": "555666777888"
                                        },
                                        {
                                            "seNumber": "9870654321"
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "paymentNetwork": "MasterCard",
                            "processors":
                            [
                                {
                                    "processorName": "Elavon",
                                    "mcAuthMids":
                                    [
                                        {
                                            "mcAuthLocationId": "222444888",
                                            "mcAuthAcquiringMid": "000111133334444",
                                            "mcAuthICA": "005555"
                                        }
                                    ],
                                    "mcClearingMids":
                                    [
                                        {
                                            "mcClearingLocationId": "222444888",
                                            "mcClearingAcquiringMid": "111133334444",
                                            "mcClearingICA": "5555"
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "paymentNetwork": "Visa",
                            "processors":
                            [
                                {
                                    "processorName": "Fiserv",
                                    "visaMids":
                                    [
                                        {
                                            "vmid": "24682468",
                                            "vsid": "131313131"
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "merchantStatus": "NO-CHANGE",
            "merchantId": "24680",
            "merchantName": "Erica's Tacos",
            "merchantCategoryCode": "5812",
            "paymentChannels":
            [
                "instore"
            ],
            "stores":
            [
                {
                    "storeId": "3001",
                    "storeName": "Erica's Tacos at Garfield",
                    "address1": "333 Garfield Ave",
                    "city": "NEW YORK",
                    "state": "NY",
                    "postalcode": "10118",
                    "countryCode": "US",
                    "processorMidChangedFlag": "N",
                    "processorMidRecords":
                    [
                        {
                            "paymentNetwork": "MasterCard",
                            "processors":
                            [
                                {
                                    "processorName": "Worldpay",
                                    "mcAuthMids":
                                    [
                                        {
                                            "mcAuthLocationId": "999999999",
                                            "mcAuthAcquiringMid": "111113333355555",
                                            "mcAuthICA": "009876"
                                        }
                                    ],
                                    "mcClearingMids":
                                    [
                                        {
                                            "mcClearingLocationId": "999999999",
                                            "mcClearingAcquiringMid": "555551111177777",
                                            "mcClearingICA": "9876"
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "paymentNetwork": "Visa",
                            "processors":
                            [
                                {
                                    "processorName": "Fiserv",
                                    "visaMids":
                                    [
                                        {
                                            "vmid": "24242424",
                                            "vsid": "363636363"
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "merchantStatus": "DELETED",
            "merchantId": "187654",
            "merchantName": "Burger Place",
            "merchantCategoryCode": "5812",
            "paymentChannels":
            [
                "instore"
            ],
            "stores":
            [
                {
                    "storeId": "4001",
                    "storeName": "Burger Place Rvier Plz",
                    "address1": "245 River Plz",
                    "city": "SAINT LOUIS",
                    "state": "MO",
                    "postalcode": "63146",
                    "countryCode": "US",
                    "processorMidChangedFlag": "N",
                    "processorMidRecords":
                    [
                        {
                            "paymentNetwork": "AmericanExpress",
                            "processors":
                            [
                                {
                                    "processorName": "AmericanExpress",
                                    "amexMids":
                                    [
                                        {
                                            "seNumber": "1133557788"
                                        },
                                        {
                                            "seNumber": "1234987650"
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "paymentNetwork": "Visa",
                            "processors":
                            [
                                {
                                    "processorName": "Elavon",
                                    "mcAuthMids":
                                    [
                                        {
                                            "mcAuthLocationId": "777888999",
                                            "mcAuthAcquiringMid": "333444555666777",
                                            "mcAuthICA": "002222"
                                        },
                                        {
                                            "mcAuthLocationId": "777888999",
                                            "mcAuthAcquiringMid": "333444555666777",
                                            "mcAuthICA": "019187"
                                        },
                                        {
                                            "mcAuthLocationId": "777888999",
                                            "mcAuthAcquiringMid": "222223333355555",
                                            "mcAuthICA": "002222"
                                        },
                                        {
                                            "mcAuthLocationId": "777888999",
                                            "mcAuthAcquiringMid": "222223333355555",
                                            "mcAuthICA": "019187"
                                        }
                                    ],
                                    "mcClearingMids":
                                    [
                                        {
                                            "mcClearingLocationId": "777888999",
                                            "mcClearingAcquiringMid": "333444555666777",
                                            "mcClearingICA": "19187"
                                        },
                                        {
                                            "mcClearingLocationId": "777888999",
                                            "mcClearingAcquiringMid": "222223333355555",
                                            "mcClearingICA": "19187"
                                        }
                                    ],
                                    "visaMids":
                                    [
                                        {
                                            "vmid": "22446688",
                                            "vsid": "333666999"
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

What’s Next