{
  "openapi": "3.0.3",
  "info": {
    "title": "Payeny Unified Payment Orchestration API",
    "description": "Production-grade payment orchestration platform for all Nexovex SaaS applications. Normalized REST API supporting multiple Stripe Connect platforms, double-entry ledger, subscriptions, and webhooks.",
    "version": "2.0.0",
    "contact": {
      "name": "Payeny Developer Support",
      "url": "https://payeny.com/docs",
      "email": "support@payeny.com"
    }
  },
  "servers": [
    {
      "url": "https://payeny.com/api/v1",
      "description": "Production Live & Sandbox API"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "payeny_test_... or payeny_live_...",
        "description": "Provide your secret API key with prefix payeny_test_ (sandbox) or payeny_live_ (production)."
      }
    },
    "schemas": {
      "StandardResponse": {
        "type": "object",
        "properties": {
          "data": { "type": "object" },
          "request_id": { "type": "string", "example": "req_8f3a9bc4" },
          "livemode": { "type": "boolean", "example": false }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "type": { "type": "string", "example": "validation_error" },
              "code": { "type": "string", "example": "invalid_amount" },
              "message": { "type": "string", "example": "Amount must be greater than zero." },
              "param": { "type": "string", "example": "amount_cents" },
              "request_id": { "type": "string", "example": "req_8f3a9bc4" }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "Health Check",
        "description": "Check API and platform profile uptime status.",
        "responses": {
          "200": { "description": "Platform operational" }
        }
      }
    },
    "/platform-profiles": {
      "get": {
        "summary": "List Platform Profiles",
        "description": "List all configured Stripe Connect platform profiles and credential health status."
      },
      "post": {
        "summary": "Create Platform Profile",
        "description": "Register a new Stripe Connect platform profile (e.g. EntryHub Payments, JumpHQ Payments, or client-owned platform)."
      }
    },
    "/merchants": {
      "get": {
        "summary": "List Merchants",
        "description": "Query merchant accounts across products."
      },
      "post": {
        "summary": "Create Merchant",
        "description": "Create a normalized merchant identity linked to a platform profile."
      }
    },
    "/merchants/{id}/onboarding-sessions": {
      "post": {
        "summary": "Generate Stripe Onboarding Session",
        "description": "Generate an account onboarding session link for merchant verification."
      }
    },
    "/customers": {
      "get": {
        "summary": "List Customers"
      },
      "post": {
        "summary": "Create Customer"
      }
    },
    "/payments": {
      "get": {
        "summary": "List Payments"
      },
      "post": {
        "summary": "Create Payment / Payment Intent",
        "description": "Create and optionally confirm a payment intent with dynamic platform fees and destination routing."
      }
    },
    "/checkout-sessions": {
      "post": {
        "summary": "Create Hosted Checkout Session",
        "description": "Generate a shareable or embeddable checkout session with Payeny styling."
      }
    },
    "/subscriptions": {
      "get": {
        "summary": "List Subscriptions"
      },
      "post": {
        "summary": "Create Subscription"
      }
    },
    "/refunds": {
      "get": {
        "summary": "List Refunds"
      },
      "post": {
        "summary": "Create Refund"
      }
    },
    "/ledger": {
      "get": {
        "summary": "Query Double-Entry Ledger"
      }
    },
    "/reconciliation/run": {
      "post": {
        "summary": "Trigger Stripe Reconciliation Audit"
      }
    }
  }
}