MID InsightsImprove this page

MID Insights provides visibility into the status and activity of your onboarded Merchant Identification Numbers (MIDs) across card networks. You can investigate MIDs in the Fidel API Dashboard or query them programmatically with the List MID Insights endpoint.

Overview

MID Insights allows you to monitor the lifecycle of your onboarded MIDs. Key capabilities include:

🔍 Health monitoring: Track the current status of every onboarded MID across card networks
📊 Network activation details: View scheme-specific identifiers (Visa, Mastercard, Amex) for each MID
🔗 Transaction linkage: Identify the first and last transactions seen on each MID for your program
📅 Date filtering: Filter MID insights by last seen transaction date ranges
🏷️ Origin tracing: Understand how each MID was discovered or sourced
📄 Dashboard and API access: Investigate MID insights in the Dashboard or retrieve paginated results through the API

Availability & Requirements

⚠️ Important Eligibility Notice: MID Insights is exclusively available to Premium Tier customers.

Activation: This feature is not enabled by default. To request access, contact your assigned Customer Success Manager (CSM).
Dashboard access: Once MID Insights is enabled for your account, select a program and open Insights in the Fidel API Dashboard.

Using MID Insights in the Dashboard

The MID Insights page provides a program-level view of your MIDs. The table shows the card network, status, MID, network-specific identifiers, origin, onboarding and offboarding dates, last transaction date and creation date.

You can sort supported columns, adjust the table density and select a row to inspect the MID insight.

MID Insights list in the Fidel API Dashboard

Filtering MID insights

Use Filter to narrow the list by fields such as card network, status, origin, brand, location, MID identifiers and last transaction date. Active filters apply to the table and to exports.

MID Insights filters in the Fidel API Dashboard

Viewing MID insight details

Select a MID insight to open its details drawer. The drawer includes:

the associated brand and location;
card-network merchant data and identifiers;
a timeline of sourcing, onboarding, offboarding and transaction activity;
links to associated transactions and MID requests, when available.

MID Insight details drawer showing network data, identifiers and timeline

Exporting MID insights

Select Export to request the current MID Insights dataset as a CSV or JSON file. The export uses the active filters. You can send the file to your account email address or specify up to five recipient email addresses.

Offboarding a MID

For an onboarded MID, open the details drawer and select Offboard MID. Choose a reason and confirm the action. This creates an offboard request; it does not immediately remove the MID from the card network.

Some MIDs cannot be offboarded in the Dashboard. If the action is unavailable, contact Fidel API support.

API Endpoints

List MID Insights

Retrieve a paginated list of MID insights for a program, including health, status, and validation details across card networks.

Endpoint: GET /programs/{programId}/mid-insights | API Reference

Request Parameters

Headers

Header Name	Type	Description	Required
`Authorization`	String	Your live secret API key (Bearer SK_KEY).	Yes
`Fidel-Version`	String	The targeted API version (e.g., `2024-11-25`).	Yes

Path Parameters

Parameter	Type	Description	Required
`programId`	uuid	The id of the program.	Yes

Query Parameters

Parameter	Type	Description	Required
`brandId`	uuid	Brand unique identifier.	No
`id`	uuid	Mid insight unique identifier.	No
`limit`	string	Numerical digit from 1 up to 100.	No
`locationId`	uuid	Location unique identifier.	No
`midId`	uuid	Merchant unique identifier.	No
`lastSeenTransactionDateFrom`	date, date-time	Filter MID insights with a last seen transaction date on or after this value for your program. Accepts ISO 8601 date or date-time format.	No
`lastSeenTransactionDateTo`	date, date-time	Filter MID insights with a last seen transaction date on or before this value for your program. Accepts ISO 8601 date or date-time format.	No
`origin`	enum	Filters MID insights by how the MID was sourced or discovered for your program. Accepted values: `address-match`, `brand-provided-mid`, `customer-provided-mid`, `manual-mid-lookup`, `missing-transaction-lookup`, `processor-provided-mid`, `system-mid-lookup`, `system-provided-mid`, `third-party-provided-mid`.	No
`seNumber`	string	The Amex Service Establishment number (Merchant ID). Must be exactly 10 numeric digits.	No
`mcAcquiringMid`	string	The Mastercard Acquiring Merchant ID.	No
`mcLocationId`	string	The Mastercard Location ID.	No
`visaAcquiringMid`	string	The Visa Acquiring Merchant ID (CAID).	No
`visaBin`	string	The Visa Bank Identification Number.	No
`vmid`	string	The Visa Merchant ID. Must be 6 to 8 numeric digits.	No
`vsid`	string	The Visa Store ID.	No
`select`	enum	Select specific response mode. Use `count` to return only the total count without items.	No
`sort`	enum	Field to sort results by. Accepted values: `created`, `onboardedAt`, `offboardedAt`, `lastSeenTransactionDate`, `sourcedAt`, `eventTs`, `updated`, `origin`, `status`, `scheme`.	No
`order`	enum	Sort order direction. Accepted values: `asc`, `desc`.	No
`start`	string	Base64-encoded pagination cursor for the next page of results. Obtained from the `last` field of a previous response.	No
`status`	enum	Filter by MID insight status. Accepted values: `onboarded`, `offboarded`.	No

Response Object

The endpoint returns a JSON object containing a paginated array of MID insights. Each entry details network activation statuses and diagnostic messages to help you resolve network mismatches quickly.

The top-level response contains:

count — Total number of matching MID insights
items — Array of MID insight records (see fields below)
last — Pagination cursor for the next page of results (pass as start in your next request)

Field	Type	Required	Description
`brandId`	string	Required	The brand (merchant) this MID insight belongs to.
`cardNetworkMerchantName`	string	Optional	Merchant name as registered with the card network.
`created`	string	Required	Timestamp when the MID insight record was created.
`id`	string	Required	Unique identifier of this MID insight record.
`locationId`	string	Required	The location this MID is associated with.
`mcAcquiringMid`	string	Optional	Mastercard acquiring MID.
`mcLocationId`	string	Optional	Mastercard location identifier.
`midId`	string	Required	The MID record this insight is linked to.
`midRequestId`	string	Optional	The MID request that originated this MID, if applicable.
`offboardedAt`	string	Optional	Timestamp when the MID was offboarded from the card network.
`onboardedAt`	string	Optional	Timestamp when the MID was onboarded to the card network.
`origin`	string	Optional	How the MID was sourced (e.g. manual, automatic). See MID Origin Types.
`programId`	string	Required	The program this MID insight belongs to.
`seNumber`	string	Optional	Service Establishment number (Amex merchant identifier).
`sourcedAt`	string	Optional	Timestamp when the MID was initially sourced or discovered.
`scheme`	string	Required	Card network scheme (e.g. `visa`, `mastercard`, `amex`).
`status`	string	Required	Current status of the MID insight (e.g. `onboarded`, `offboarded`, `sourced`).
`visaAcquiringMid`	string	Optional	Visa acquiring MID.
`visaBin`	string	Optional	Visa Bank Identification Number.
`vmid`	string	Optional	Visa Merchant ID (assigned by Visa).
`vsid`	string	Optional	Visa Store ID.
`lastSeenTransactionDate`	string	Optional	Date of the most recent transaction seen on this MID for your program.
`lastSeenTransactionId`	string	Optional	ID of the most recent transaction seen on this MID for your program.
`firstTransactionClearingId`	string	Optional	ID of the first clearing transaction on this MID.
`firstTransactionAuthId`	string	Optional	ID of the first authorisation transaction on this MID for your program.

MID Origin Types

The origin field describes how each MID was discovered or sourced for a location.

Origin	Response Field Value	Description
Address match	`address-match`	MID was identified as part of searching the address automatically on the card network and matching MIDs based on brand name and address details provided by the client on location level.
Brand provided	`brand-provided-mid`	The MID was provided directly by the brand or merchant.
Customer provided	`customer-provided-mid`	The client added the MID to the location or to a MID request for onboarding.
Manual lookup	`manual-mid-lookup`	Fidel support manually looked up the card network MID for an onboarded location through the card networks.
Missing transaction lookup	`missing-transaction-lookup`	A transaction was made at an onboarded location and the MID was identified from the transaction data (most accurate).
Processor provided	`processor-provided-mid`	The MID was provided by the payment processor or acquirer (e.g., Stripe, Adyen).
System MID lookup	`system-mid-lookup`	A Mastercard CAID (Card Acceptor ID) triggered the system to look up the Visa MIDs/CAIDs through the Mastercard CAID.
System provided	`system-provided-mid`	The MID was automatically identified and provided by the Fidel system.
Third-party provided	`third-party-provided-mid`	A third-party service (e.g., Incubit) sourced the MID for the location.

Scheme-Specific Fields

Depending on the card network (scheme) of a MID insight, different identifier fields will be populated in the response.

Field	Scheme	Description
`seNumber`	Amex	Amex MID number (Service Establishment number).
`mcAcquiringMid`	Mastercard	Mastercard Acquiring Merchant ID.
`mcLocationId`	Mastercard	Mastercard Location ID.
`visaAcquiringMid`	Visa	Visa Acquiring Merchant ID (CAID).
`visaBin`	Visa	Visa Bank Identification Number.
`vmid`	Visa	Visa Merchant ID (assigned by Visa).
`vsid`	Visa	Visa Store ID.
`cardNetworkMerchantName`	All schemes	Merchant name as registered with the card network at the scheme for this MID.
`lastSeenTransactionDate`	All schemes	Date of the last transaction tracked by Fidel for your program on this MID.
`lastSeenTransactionId`	All schemes	Last tracked Fidel transaction ID on this MID for your program (confirms whether the MID is still active).
`firstTransactionClearingId`	All schemes	First Fidel clearing transaction ID tracked on this MID.
`firstTransactionAuthId`	All schemes	First Fidel authorisation transaction ID tracked on this MID for your program.

Implementation Example

123456
curl --request GET \
  --url 'https://api.fidel.uk/v1/programs/programId/mid-insights?sort=created&order=desc' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer clsk_live_...' \
  --header 'Fidel-Version: 2024-11-25'

Error Codes

HTTP Status	Error Code	Description
`401`	`unauthorized`	The API key provided is invalid or expired.
`403`	`tier_restricted`	Feature locked. Your account is not configured for Premium tier access.
`404`	`resource_not_found`	The requested `programId` could not be found.
`429`	`rate_limit_exceeded`	Request volume limits exceeded. Implement request back-off mechanisms.

Documentation