{
  "openapi": "3.0.3",
  "info": {
    "title": "Zateway Payment API",
    "version": "1.0.0",
    "description": "Zateway is a non-custodial crypto payment gateway. Accept USDT & USDC stablecoin payments on Polygon, Solana, Base, BSC, Arbitrum, and Optimism with a 1% flat fee. Direct-to-wallet settlement. AI agent compatible.",
    "contact": {
      "name": "Zateway Support",
      "url": "https://zateway.com/contact",
      "email": "support@zateway.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://zateway.com/terms"
    }
  },
  "servers": [
    { "url": "https://zateway.com/api/v1", "description": "Production" },
    { "url": "https://zateway.com/api/v1", "description": "Sandbox (use zate_test_* keys)" }
  ],
  "tags": [
    { "name": "Sessions", "description": "Payment session management" },
    { "name": "Webhooks", "description": "Webhook configuration and events" },
    { "name": "Health", "description": "Service health and status" }
  ],
  "paths": {
    "/sessions": {
      "post": {
        "tags": ["Sessions"],
        "operationId": "createSession",
        "summary": "Create a payment session",
        "description": "Creates a new payment session for accepting USDT or USDC on the specified blockchain. Returns a checkout URL for customers or AI agents.",
        "security": [{ "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["amount", "currency", "chain"],
                "properties": {
                  "amount": { "type": "string", "description": "Payment amount in token units", "example": "50.00" },
                  "currency": { "type": "string", "enum": ["USDT", "USDC"] },
                  "chain": { "type": "string", "enum": ["polygon", "solana", "base", "bsc", "arbitrum", "optimism"] },
                  "webhookUrl": { "type": "string", "format": "uri" },
                  "successUrl": { "type": "string", "format": "uri" },
                  "metadata": { "type": "object", "additionalProperties": { "type": "string" } },
                  "expiresIn": { "type": "integer", "default": 3600 }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Payment session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSession" } } } },
          "400": { "description": "Invalid request" },
          "401": { "description": "Invalid API key" },
          "429": { "description": "Rate limited" }
        }
      }
    },
    "/sessions/{sessionId}": {
      "get": {
        "tags": ["Sessions"],
        "operationId": "getSession",
        "summary": "Get payment session status",
        "description": "Retrieve status of a payment session. Use for polling in AI agent workflows.",
        "security": [{ "BearerAuth": [] }],
        "parameters": [{ "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Session details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSession" } } } },
          "404": { "description": "Not found" }
        }
      }
    },
    "/health": {
      "get": {
        "tags": ["Health"],
        "operationId": "healthCheck",
        "summary": "Service health check",
        "responses": { "200": { "description": "Healthy" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Use zate_live_* for production, zate_test_* for sandbox." }
    },
    "schemas": {
      "PaymentSession": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "sess_abc123" },
          "status": { "type": "string", "enum": ["created", "pending", "confirming", "confirmed", "settled", "expired", "failed"] },
          "amount": { "type": "string", "example": "50.00" },
          "currency": { "type": "string", "enum": ["USDT", "USDC"] },
          "chain": { "type": "string", "enum": ["polygon", "solana", "base", "bsc", "arbitrum", "optimism"] },
          "checkoutUrl": { "type": "string", "format": "uri" },
          "paymentAddress": { "type": "string" },
          "txHash": { "type": "string", "nullable": true },
          "confirmations": { "type": "integer" },
          "metadata": { "type": "object", "additionalProperties": { "type": "string" } },
          "createdAt": { "type": "string", "format": "date-time" },
          "expiresAt": { "type": "string", "format": "date-time" }
        }
      }
    }
  }
}