REST API Option

Abstract

This document describes the REST API integration option for merchant data management, designed to enable near real-time updates as an alternative to daily SFTP file uploads. The REST API uses the same JSON schema as the SFTP method, but omits the header record and merchant status field, deriving status from the HTTP method instead (PUT for UPSERT, DELETE for DELETED).

The API processes one merchant record per request. Partners use the endpoint PUT /api/v1/partner/merchants/{external_merchant_id} to create or update merchant records, and DELETE /api/v1/partner/merchants/{external_merchant_id} to remove a merchant. Requests are made using the partner’s own merchant ID and only need to be sent when changes occur. The API responses confirm that requests have been accepted for processing.

This approach streamlines merchant updates and deletions, ensuring efficient and timely data synchronization.

How It Works

In addition to SFTP, we also provide a REST API to make it easier to enable near real-time merchant updates instead of the daily merchant file dump
We will use the same JSON schema as defined for SFTP to have 1:1 parity, but with the following differences:
- No Header Record.
- No Merchant Status - it will be derived from the HTTP method, HTTP Method PUT -> merchantStatus=UPSERT”, HTTP Method DELETE -> merchantStatus=DELETED
- One Merchant Record at a time.

Recommendations on how to call

Partner begins with calling the Merchant endpoint PUT /api/v1/partner/merchants/{external_merchant_id} one merchant at a time within the limits of the RPS.
The partner doesn’t need to resend the same merchant again unless there are any changes to the merchant details or the merchant needs to be taken down.
To update a merchant, the partner must call the same endpoint PUT /api/v1/partner/merchants/{external_merchant_id}as used for the creation.
To delete a merchant partner must call the DELETE /api/v1/partner/merchants/{external_merchant_id} endpoint with no request payload.

Create or Update the Merchant details using the self-provided merchant ID

Hostname	api.cardlytics.com
Endpoint	`/api/v1/partner/merchants/{external_merchant_id}`
Method	PUT
Content-Type	application/json
Request Payload	Payload
Response	`{"message":"Request accepted for processing", "trace_id": "req-98765" }`

Delete the Merchant using the self-provided merchant ID

Hostname	api.cardlytics.com
Endpoint	`/api/v1/partner/merchants/{external_merchant_id}`
Method	DELETE
Content-Type	application/json
Response	{ "message":"Request accepted for processing", "trace_id": "req-98765" }

Sample Request

 {
            "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":
                    [
                        "[email protected]"
                    ],
                    "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"
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }