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.
  /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
  /checkout-sessions:
    post:
      summary: Create Hosted Checkout Session
  /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