{
  "openapi": "3.1.0",
  "info": {
    "title": "MerchantHQ Data API",
    "summary": "Read-only public data on UK card-payment acquirers and fees.",
    "description": "Machine-readable access to the MerchantHQ UK Card Acquirer Index: factual acquirer terms (headline rate, settlement timing, contract length, channels) plus regulatory identifiers where verified, and a current fees snapshot. Source of truth is the on-site Card Acquirer Index Dataset. Read-only, no authentication, no PII, CC BY 4.0. Also exposed as an MCP server at /mcp (see /.well-known/mcp.json).",
    "version": "2026-05-25",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "MerchantHQ",
      "url": "https://merchanthq.co.uk/data/api/"
    }
  },
  "servers": [
    { "url": "https://merchanthq.co.uk", "description": "Production" }
  ],
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://merchanthq.co.uk/data/api/"
  },
  "paths": {
    "/api/acquirers": {
      "get": {
        "operationId": "listAcquirers",
        "summary": "List UK card-payment acquirers in the MerchantHQ panel",
        "description": "Returns all tracked acquirers, or a filtered subset when query params are supplied.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free-text match on acquirer name, notes and terms.",
            "schema": { "type": "string" }
          },
          {
            "name": "tier",
            "in": "query",
            "required": false,
            "description": "Filter by acquirer category.",
            "schema": {
              "type": "string",
              "enum": ["mainstream", "bank", "high-risk", "online-gateway"]
            }
          },
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "description": "Filter by sales channel the acquirer supports.",
            "schema": {
              "type": "string",
              "enum": ["in-person", "online", "omnichannel"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of acquirers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "count": { "type": "integer" },
                    "acquirers": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Acquirer" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/acquirers/{slug}": {
      "get": {
        "operationId": "getAcquirer",
        "summary": "Get a single acquirer by slug",
        "description": "Accepts the canonical slug (e.g. dojo) or the review-page slug (e.g. dojo-go).",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "dojo"
          }
        ],
        "responses": {
          "200": {
            "description": "The matching acquirer.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "acquirer": { "$ref": "#/components/schemas/Acquirer" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No acquirer matches the slug.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/fees-snapshot": {
      "get": {
        "operationId": "getFeesSnapshot",
        "summary": "Current UK card-payment fees snapshot",
        "description": "Range of published headline percentage rates across the panel, panel size and a per-tier breakdown. Acquirers that price bespoke per merchant are excluded from the range.",
        "responses": {
          "200": {
            "description": "Fees snapshot.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FeesSnapshot" }
              }
            }
          }
        }
      }
    },
    "/api/high-risk": {
      "get": {
        "operationId": "getHighRiskMatrix",
        "summary": "UK high-risk merchant-account matrix by vertical",
        "description": "Typical UK card-acquiring blended-rate and rolling-reserve bands per high-risk vertical (CBD, vape, gambling, crypto, adult, travel, forex and more), the legal status, and whether a named UK acquirer panel works with the category or it routes to a specialist per application. Bands are typical onboarding figures, not quoted offers; MerchantHQ is a broker and acceptance is underwritten by the acquirer.",
        "responses": {
          "200": {
            "description": "High-risk vertical matrix.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "count": { "type": "integer" },
                    "verticals": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": { "type": "string" },
                          "vertical": { "type": "string" },
                          "category": { "type": "string" },
                          "legal_status": { "type": "string" },
                          "typical_rate": { "type": "string" },
                          "rolling_reserve": { "type": "string" },
                          "uk_acquirer_route": { "type": "string", "enum": ["named-uk-panel", "specialist-per-application"] },
                          "url": { "type": "string", "format": "uri" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Identifiers": {
        "type": "object",
        "properties": {
          "legal_entity": { "type": "string" },
          "fca_frn": { "type": "string" },
          "fca_register_url": { "type": "string", "format": "uri" },
          "companies_house_number": { "type": "string" },
          "companies_house_url": { "type": "string", "format": "uri" },
          "open_corporates_url": { "type": "string", "format": "uri" },
          "last_verified": { "type": "string", "format": "date" }
        }
      },
      "Acquirer": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "tier": {
            "type": "string",
            "enum": ["mainstream", "bank", "high-risk", "online-gateway"]
          },
          "channels": {
            "type": "array",
            "items": { "type": "string", "enum": ["in-person", "online", "omnichannel"] }
          },
          "headline_rate": { "type": "string" },
          "settlement": { "type": "string" },
          "contract": { "type": "string" },
          "notes": { "type": "string" },
          "review_url": { "type": "string", "format": "uri" },
          "identifiers": { "$ref": "#/components/schemas/Identifiers" }
        },
        "required": ["slug", "name", "tier", "channels", "headline_rate"]
      },
      "FeesSnapshot": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "as_of": { "type": "string", "format": "date" },
          "currency": { "type": "string" },
          "region": { "type": "string" },
          "published_headline_rate": {
            "type": "object",
            "properties": {
              "min_percent": { "type": ["number", "null"] },
              "max_percent": { "type": ["number", "null"] },
              "acquirers_with_published_rate": { "type": "integer" },
              "note": { "type": "string" }
            }
          },
          "acquirers_count": { "type": "integer" },
          "tiers": {
            "type": "object",
            "properties": {
              "mainstream": { "type": "integer" },
              "bank": { "type": "integer" },
              "high-risk": { "type": "integer" },
              "online-gateway": { "type": "integer" }
            }
          },
          "source": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "detail": { "type": "string" }
        }
      }
    }
  }
}