{
  "openapi": "3.1.0",
  "info": {
    "title": "AcmePay API",
    "version": "2.3.1",
    "description": "Payments, payouts and reconciliation API. Contact: security@acmepay.duckdns.org",
    "contact": { "name": "AcmePay Developer Support", "url": "https://portal.acmepay.duckdns.org" }
  },
  "servers": [
    { "url": "https://api.acmepay.duckdns.org/api/v2", "description": "Production" },
    { "url": "https://staging-api.acmepay.duckdns.org/api/v2", "description": "Staging (internal)" },
    { "url": "https://sandbox.acmepay.duckdns.org/api/v2", "description": "Sandbox" }
  ],
  "components": {
    "securitySchemes": {
      "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" },
      "legacyKey": { "type": "apiKey", "in": "header", "name": "X-AcmePay-Key", "description": "v1 only, deprecated" }
    }
  },
  "security": [ { "bearer": [] } ],
  "paths": {
    "/auth/token": {
      "post": { "summary": "Exchange credentials for a bearer token", "security": [], "responses": { "200": { "description": "token" } } }
    },
    "/payments": {
      "get": { "summary": "List payments", "responses": { "200": { "description": "ok" } } },
      "post": { "summary": "Create a payment", "responses": { "201": { "description": "created" } } }
    },
    "/payments/{id}": {
      "get": { "summary": "Get a payment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok" } } }
    },
    "/payments/{id}/capture": {
      "post": { "summary": "Capture an authorised payment", "responses": { "200": { "description": "ok" } } }
    },
    "/payouts": {
      "post": { "summary": "Create a payout", "responses": { "201": { "description": "created" } } }
    },
    "/customers": {
      "get": { "summary": "List customers", "responses": { "200": { "description": "ok" } } }
    },
    "/webhooks": {
      "get": { "summary": "List webhook endpoints", "responses": { "200": { "description": "ok" } } },
      "post": { "summary": "Register a webhook endpoint", "responses": { "201": { "description": "created" } } }
    },
    "/status": {
      "get": { "summary": "Health check", "security": [], "responses": { "200": { "description": "ok" } } }
    },
    "/debug/config": {
      "get": {
        "summary": "Return effective service configuration",
        "deprecated": true,
        "description": "Diagnostic endpoint. Enabled on staging only. Removed from production in v2.3.",
        "responses": { "200": { "description": "config dump" }, "404": { "description": "disabled" } }
      }
    },
    "/internal/reports": {
      "get": {
        "summary": "Generate a reconciliation report",
        "description": "Internal use only. Requires VPN source address. Not available on the public gateway.",
        "responses": { "200": { "description": "ok" }, "403": { "description": "forbidden" } }
      }
    }
  }
}