{
  "openapi": "3.0.3",
  "info": {
    "title": "Dark Dollars BIN Lookup API",
    "description": "Free, key-less REST API over an open dataset of 374,788 payment card BIN prefixes covering 225 countries, 18,373 issuing banks and 71 card networks. Returns the issuer, card scheme, product type, card category and issuing country for any prefix.\n\nAttribution: the underlying BIN list is published by venelinkochev/bin-list-data under a Creative Commons Attribution 4.0 International licence.",
    "version": "1.0.0",
    "contact": {
      "name": "Dark Dollars",
      "url": "https://darkdollars.ru/api-docs.html"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://darkdollars.ru",
      "description": "Production"
    }
  ],
  "tags": [
    {"name": "BIN", "description": "Bank Identification Number lookups"},
    {"name": "Service", "description": "Service health and dataset statistics"}
  ],
  "paths": {
    "/api/bin/{prefix}": {
      "get": {
        "tags": ["BIN"],
        "summary": "Look up a single card prefix",
        "description": "Resolves a 6 to 11 digit prefix. Prefixes longer than six digits are matched on their first six digits.",
        "operationId": "getBin",
        "parameters": [
          {
            "name": "prefix",
            "in": "path",
            "required": true,
            "description": "Card prefix, 6 to 11 digits.",
            "schema": {"type": "string", "pattern": "^[0-9]{6,11}$"},
            "example": "424242"
          }
        ],
        "responses": {
          "200": {
            "description": "The matching record.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/BinRecord"},
                "example": {
                  "bin": "424242",
                  "scheme": "VISA",
                  "type": "CREDIT",
                  "category": "CLASSIC",
                  "issuer": "STRIPE PAYMENTS UK, LTD.",
                  "country": "GB",
                  "matched": "424242",
                  "exact": true
                }
              }
            }
          },
          "404": {
            "description": "The prefix is not present in the dataset.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Error"}
              }
            }
          }
        }
      }
    },
    "/api/bin": {
      "get": {
        "tags": ["BIN"],
        "summary": "Look up a prefix using a query parameter",
        "parameters": [
          {
            "name": "prefix",
            "in": "query",
            "required": true,
            "schema": {"type": "string", "pattern": "^[0-9]{6,11}$"},
            "example": "424242"
          }
        ],
        "responses": {
          "200": {
            "description": "The matching record.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/BinRecord"}
              }
            }
          },
          "400": {
            "description": "Missing prefix parameter.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {
            "description": "The prefix is not present in the dataset.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          }
        }
      }
    },
    "/api/bulk": {
      "get": {
        "tags": ["BIN"],
        "summary": "Look up up to 100 prefixes in one request",
        "parameters": [
          {
            "name": "prefixes",
            "in": "query",
            "required": true,
            "description": "Comma or whitespace separated list of prefixes, up to 100.",
            "schema": {"type": "string"},
            "example": "424242,555555,378282"
          }
        ],
        "responses": {
          "200": {
            "description": "One result entry per requested prefix, in the requested order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {"type": "integer", "example": 3},
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "prefix": {"type": "string"},
                          "result": {
                            "oneOf": [
                              {"$ref": "#/components/schemas/BinRecord"},
                              {"type": "null"}
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "tags": ["Service"],
        "summary": "Dataset statistics",
        "responses": {
          "200": {
            "description": "Counts describing the published dataset.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prefixes": {"type": "integer", "example": 374788},
                    "countries": {"type": "integer", "example": 225},
                    "issuers": {"type": "integer", "example": 18373},
                    "brands": {"type": "integer", "example": 71},
                    "updated": {"type": "number"}
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": ["Service"],
        "summary": "Service health check",
        "responses": {
          "200": {
            "description": "The service is running.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {"type": "boolean", "example": true},
                    "service": {"type": "string", "example": "darkdollars-bin-api"},
                    "prefixes": {"type": "integer"}
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BinRecord": {
        "type": "object",
        "properties": {
          "bin": {"type": "string", "description": "The matched six-digit BIN.", "example": "424242"},
          "scheme": {"type": "string", "description": "Card network.", "example": "VISA"},
          "type": {"type": "string", "description": "Product type: DEBIT, CREDIT or CHARGE CARD.", "example": "CREDIT"},
          "category": {"type": "string", "nullable": true, "description": "Card level such as CLASSIC or PLATINUM.", "example": "CLASSIC"},
          "issuer": {"type": "string", "nullable": true, "description": "Name of the issuing institution.", "example": "STRIPE PAYMENTS UK, LTD."},
          "country": {"type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 country of the issuer.", "example": "GB"},
          "matched": {"type": "string", "description": "The prefix that was actually resolved."},
          "exact": {"type": "boolean", "description": "True when the requested prefix was exactly six digits."}
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {"type": "string", "example": "prefix not found"},
          "prefix": {"type": "string", "example": "999999"}
        }
      }
    }
  }
}