MID Management APIImprove this page

Manage the full lifecycle of Merchant IDs (MIDs) for your card-linked programs. Onboard, offboard, and reassign MIDs to control where you receive transaction data.

Merchant IDs (MIDs)

What is a MID

A Merchant ID (MID) is a unique identifier assigned to a physical or online merchant location by their payment processor. This identification number is crucial for the payment ecosystem to function properly.

Key functions of a MID:

🏪 Location identifier: Each MID is associated with a specific merchant location, not the brand as a whole
💰 Payment routing: Enables payment processors to route funds to the correct merchant account
📍 Transaction attribution: Transmitted with cardholder information to ensure accurate transaction reconciliation
🔍 Data tracking: Allows card-linked programs to identify and track transactions at specific merchant locations

💡 Think of it as an address: Without a MID, the payment networks wouldn't know where to send the merchant's money. In card-linked programs, MIDs enable you to receive transaction data from specific merchant locations enrolled in your program.

For more information, see the Locations/Merchant Onboarding FAQs.

View and manage Merchant IDs (MIDs) onboarded for your program by selecting a Program from the Programs page. This opens the 'Merchant IDs' tab in the Fidel Dashboard.

All onboarded MIDs for the selected program are displayed on this page. You can also retrieve this information via the API: Get MID | List MIDs

Onboard MID

Onboard MIDs to existing locations via the Create MID Request API or the Fidel Dashboard. Learn more about what is a MID request.

Dashboard Walkthrough

Step-by-step:

Navigate to Programs - Select your program from the Programs page to open the Merchant IDs tab
Initiate onboarding - Click + Onboard MID in the upper right
Select location - Choose the brand and location where you want to onboard the MID, then click Next
Choose MID origin - Select the appropriate origin from the dropdown (see table below for descriptions)
Enter MID details - Select the card network and enter the MID value
Submit - Click Done to create the request

MID Origin Types

Origin	Description
Missing transaction lookup	A transaction was made at an onboarded location and the MID was identified from the transaction data (most accurate).
Manual lookup	Fidel support manually looked up the card network MID for an onboarded location through the card networks.
Brand provided	The MID was provided directly by the brand/merchant.
Processor provided	The MID was provided by the payment processor or acquirer (e.g., Stripe, Adyen).
Third-party provided	A third-party service (e.g., Incubit) sourced the MID for the location.

⏱️ Processing Time: MID requests are processed asynchronously and typically take up to 7 days to complete due to card network constraints.

Bulk MID action (onboard, offboard or re-assign)

For Bulk MID requests like onboarding, reassigning or offboarding multiple MIDs at once, use the CSV bulk upload feature in the Fidel Dashboard. This is ideal when you have a large number of MIDs to onboard across multiple locations.

Dashboard Walkthrough

Step-by-step:

Navigate to Programs - Select your program from the Programs page to open the Merchant IDs tab
Initiate bulk upload - Click Bulk Upload in the upper right.
Download template - Click Download CSV Template to get the required file format
Prepare your CSV - Fill in the template with your MID data (see format requirements below)
Upload file - Drag and drop your CSV file or click to browse and select it
Review entries - Verify the parsed MID entries are correct
Submit - Click Upload to create the onboard requests for all MIDs

CSV Format Requirements

Your CSV file must include the following columns:

Column	Required	Description
`action`	Yes	The MID request action. Accepted values: `onboard`, `offboard`, `reassign`.
`locationId`	Yes	The unique identifier of the location where the MID should be onboarded.
`scheme`	Yes	The card network for the MID. Accepted values: `visa`, `mastercard`, `amex`.
`origin`	Onboard only	The source of the MID. Required for onboard actions. See MID Origin Types for accepted values.

Example CSV:

12345
action,locationId,origin,scheme,seNumber,mcAcquiringMid,mcLocationId,visaAcquiringMid,visaBin,vmid,vsid,midId,newLocationId,reason
onboard,f6200ed2-8a2d-4a6b-beb1-bf411539a1a8,third-party-provided-mid,mastercard,,214875,891234,,,,,,,
onboard,f6200ed2-8a2d-4a6b-beb1-bf411539a1a8,brand-provided-mid,visa,,,,567890,412345,,,,,
onboard,bdfe8b39-9e12-4e3b-bb97-1ee8c3043f7b,manual-mid-lookup,visa,,,,,,789012,65432110,,,

💡 Tip: Use the downloadable CSV template to ensure your file has the correct format and column headers.

⚠️ Limits: Each bulk upload supports up to 250 MIDs per file. For larger batches, split your data into multiple CSV files.

⏱️ Processing Time: Each MID in the bulk upload creates an individual MID request. Processing times remain the same (up to 7 days per request). You can track the status of all requests in the MID Requests tab.

Offboard MID

Offboard a MID via the Create MID Request API with the action 'offboard', or via the Fidel Dashboard.

Dashboard Walkthrough

Step-by-step:

Locate MID - Find the MID you want to offboard in the Merchant IDs list
Open actions menu - Click the three dots next to the relevant MID
Select offboard - Choose Offboard MID from the dropdown menu
Choose reason - Select the reason for offboarding from the dropdown
Acknowledge impact - Confirm that you understand you will no longer receive transactions for this MID
Submit - Click Confirm to create the offboard request

📋 Next Steps: This creates a new MID request. See the MID Requests section to track the status.

Reassign MID

Reassign a MID to a different location via the Create MID Request API with the action 'reassign', or via the Fidel Dashboard.

Dashboard Walkthrough

Step-by-step:

Locate MID - Find the MID you want to reassign in the Merchant IDs list
Open actions menu - Click the three dots next to the relevant MID
Select reassign - Choose Reassign MID from the dropdown menu
Choose reason - Select the reason for reassigning the MID
Select new location - Choose the brand and location where the MID should be assigned
Submit - Click Done to create the reassignment request

📋 Next Steps: This creates a new MID request. See the MID Requests section to track the status.

MID Requests

What is a MID Request

A MID request is a workflow instruction to the Fidel platform to source, remove, or re-link a card-network MID for a specific merchant location within a program.

Supported actions map to the MID lifecycle:

✅ onboard: Ask Fidel to provision or ingest a MID for AMEX, Mastercard, or Visa.
❌ offboard: Remove an existing MID that should no longer be associated with a location, stopping the transaction ingestion pipeline.
🔄 reassign: Move an existing MID from one location to another.

📊 Request Tracking: Every request is tracked independently so you can poll for status, inspect error details, and retrieve the card-network outcome (returned MID identifiers) once processing finishes.

MID requests are displayed under the 'Requests' tab on the Dashboard. All MID requests you create to onboard, offboard, or reassign MIDs will be visible on this tab or can be retrieved via these endpoints: Get MID Request | List MID Requests

The different statuses of MID requests are defined below:

Status	Description
	The request has been received and is queued for processing.
	The request is currently being processed by the card networks.
	The request has been successfully completed and the MID has been onboarded, offboarded, or reassigned.
	The request could not be completed. Check the error details for more information.

Webhooks

Subscribe to webhooks to receive real-time notifications when a MID request succeeds or fails:

✅ mid-request.succeeded
❌ mid-request.failed

You can also view the status on the Dashboard. To understand why a MID request failed, inspect the raw data by clicking on the failed request:

mid-request.json
1234567891011121314151617181920212223
{
  "accountId": "f7a83b85-2452-4715-806c-35be51b6515b",
  "action": "onboard",
  "brandId": "50c28205-ff3c-440e-8e27-42b7770d8dd9",
  "created": "2025-10-06T16:57:44.230Z",
  "estimatedCompletionDate": "2025-10-07T16:57:44.230Z",
  "id": "317e0700-2a9e-44d3-9380-6c06c6ef3593",
  "live": true,
  "locationId": "ed8ef30e-5e33-4bf8-93eb-aaa8ee8c2de4",
  "origin": "missing-transaction-lookup",
  "programId": "a7ce6bed-efad-4582-b9c2-a583185fa39e",
  "result": {
    "error": {
      "code": "card-scheme-mid-not-found",
      "message": "Merchant not valid"
    }
  },
  "scheme": "amex",
  "seNumber": "3022430235",
  "status": "failed",
  "updated": "2025-10-06T16:57:55.033Z"
}

Error Codes

These are the error codes for failed MID requests:

Error Code	Message	Description
`card-scheme-mid-not-found`	Merchant not valid	The card scheme could not locate a valid MID for this merchant.
`program-not-configured`	Client program not configured with card scheme	The client program has not been configured with the card scheme, so the MID cannot be onboarded.
`card-scheme-shared-mid`	Shared MID	The MID provided for onboarding is a 'shared MID'. See 'Shared MIDs' in the FAQs for more information.
`no-mids-found`	No MIDs were found at the card scheme	The MID provided as part of the MID request does not exist at the card network/scheme.
`visa-invalid-input`	Invalid input provided for Visa	One or more Visa-specific MID fields (e.g., VMID, VSID, Visa BIN, or Visa Acquiring MID) contain invalid values.
`mid-onboarding-conflict`	MID is onboarded to a different location or was deleted before this request completed	The request could not be completed because the MID state changed during processing: it is now linked to another location, or it was removed before onboarding finished.
`unexpected-error`	Unexpected error	An unexpected exception occurred during processing.

Documentation

MID Management APIImprove this page

Merchant IDs (MIDs)

What is a MID

Onboard MID

Dashboard Walkthrough

MID Origin Types

Bulk MID action (onboard, offboard or re-assign)

Dashboard Walkthrough

CSV Format Requirements

Offboard MID

Dashboard Walkthrough

Reassign MID

Dashboard Walkthrough

MID Requests

What is a MID Request

Webhooks

mid-request.json

Error Codes