{
  "openapi": "3.1.0",
  "info": {
    "title": "Rendben API",
    "version": "1.0.0",
    "description": "Merchant-scoped payment intents, products, entitlement verification, and signed lifecycle webhooks."
  },
  "servers": [{ "url": "https://rendben.com" }],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/api/v1/products": {
      "get": {
        "summary": "List products",
        "responses": {
          "200": {
            "description": "Workspace products",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["products"],
                  "properties": {
                    "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "summary": "Create a product",
        "description": "Requires a read-write API key and Idempotency-Key header.",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreate" } }
          }
        },
        "responses": {
          "201": {
            "description": "Product created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["product"],
                  "properties": { "product": { "$ref": "#/components/schemas/Product" } }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/v1/payment-intents": {
      "post": {
        "summary": "Create a payment intent",
        "description": "Creates a resumable checkout for an active one-time product. Requires a read-write API key.",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntentCreate" } } }
        },
        "responses": {
          "201": {
            "description": "Payment intent created",
            "content": { "application/json": { "schema": {
              "type": "object",
              "required": ["paymentIntent"],
              "properties": { "paymentIntent": { "$ref": "#/components/schemas/PaymentIntent" } }
            } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/api/v1/payment-intents/{intentId}": {
      "get": {
        "summary": "Retrieve a payment intent",
        "parameters": [{
          "name": "intentId", "in": "path", "required": true,
          "schema": { "type": "string", "pattern": "^pi_[A-Za-z0-9_-]{20,40}$" }
        }],
        "responses": {
          "200": {
            "description": "Merchant payment intent",
            "content": { "application/json": { "schema": {
              "type": "object",
              "required": ["paymentIntent"],
              "properties": { "paymentIntent": { "$ref": "#/components/schemas/PaymentIntent" } }
            } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "description": "Payment intent not found" }
        }
      }
    },
    "/api/v1/subscriptions": {
      "get": {
        "summary": "List and verify subscriptions",
        "description": "Omit customer_email for a merchant-wide list and aggregate lifecycle counts. Add customer_email for entitlement verification.",
        "parameters": [
          {
            "name": "customer_email",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "email", "maxLength": 254 }
          },
          { "$ref": "#/components/parameters/ProductId" },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["authorization_pending", "activating", "active", "past_due", "cancel_pending", "cancelled", "revoked", "expired", "failed", "all"],
              "default": "all"
            }
          },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Page" }
        ],
        "responses": {
          "200": {
            "description": "Matching merchant subscriptions",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SubscriptionVerification" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/v1/orders": {
      "get": {
        "summary": "Verify one-time orders for a customer",
        "parameters": [
          { "$ref": "#/components/parameters/CustomerEmail" },
          { "$ref": "#/components/parameters/ProductId" },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["paid", "pending", "processing", "expired", "failed", "all"],
              "default": "paid"
            }
          },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Page" }
        ],
        "responses": {
          "200": {
            "description": "Matching merchant orders",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OrderVerification" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "rdb_live_ API key"
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "Unique key for this intended write. The same key and body replay the original response for 24 hours.",
        "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }
      },
      "CustomerEmail": {
        "name": "customer_email",
        "in": "query",
        "required": true,
        "schema": { "type": "string", "format": "email", "maxLength": 254 }
      },
      "ProductId": {
        "name": "product_id",
        "in": "query",
        "required": false,
        "schema": { "type": "string", "pattern": "^prod_[A-Za-z0-9_-]{16,40}$" }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }
      },
      "Page": {
        "name": "page",
        "in": "query",
        "required": false,
        "schema": { "type": "integer", "minimum": 1, "default": 1 }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid query",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Conflict": {
        "description": "Idempotency key conflict or request still processing",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": { "error": { "type": "string" } }
      },
      "BillingInterval": {
        "type": "object",
        "required": ["unit", "count"],
        "properties": {
          "unit": { "type": "string", "enum": ["day", "week", "month", "year"] },
          "count": { "type": "integer", "minimum": 1, "maximum": 12 }
        }
      },
      "ProductCreate": {
        "type": "object",
        "required": ["name", "description", "priceUsdc", "pricingModel"],
        "properties": {
          "name": { "type": "string", "minLength": 2, "maxLength": 120 },
          "description": { "type": "string", "maxLength": 500 },
          "returnUrl": { "type": "string", "format": "uri" },
          "coverImageUrl": { "type": "string", "format": "uri" },
          "priceUsdc": { "type": "string", "pattern": "^(?:0|[1-9]\\d{0,6})(?:\\.\\d{1,6})?$" },
          "pricingModel": { "type": "string", "enum": ["one_time", "recurring"] },
          "billingInterval": {
            "oneOf": [
              { "$ref": "#/components/schemas/BillingInterval" },
              { "type": "null" }
            ]
          }
        }
      },
      "Product": {
        "allOf": [
          { "$ref": "#/components/schemas/ProductCreate" },
          {
            "type": "object",
            "required": ["id", "status", "createdAt", "updatedAt"],
            "properties": {
              "id": { "type": "string" },
              "status": { "type": "string", "enum": ["active", "archived"] },
              "createdAt": { "type": "string", "format": "date-time" },
              "updatedAt": { "type": "string", "format": "date-time" }
            }
          }
        ]
      },
      "PaymentIntentCreate": {
        "type": "object",
        "required": ["productId", "customer"],
        "properties": {
          "productId": { "type": "string", "pattern": "^prod_[A-Za-z0-9_-]{20,40}$" },
          "customer": {
            "type": "object",
            "required": ["email"],
            "properties": {
              "email": { "type": "string", "format": "email", "maxLength": 254 },
              "reference": { "type": "string", "maxLength": 255 }
            }
          },
          "metadata": { "type": "object", "additionalProperties": true }
        }
      },
      "PaymentIntent": {
        "type": "object",
        "required": ["id", "object", "status", "productId", "customerEmail", "amountUsdc", "merchantAmountUsdc", "feeAmountUsdc", "expiresAt"],
        "properties": {
          "id": { "type": "string" },
          "object": { "type": "string", "const": "payment_intent" },
          "status": { "type": "string", "enum": ["pending", "processing", "confirmed", "expired", "failed"] },
          "productId": { "type": "string" },
          "customerEmail": { "type": "string", "format": "email" },
          "customerReference": { "type": ["string", "null"] },
          "metadata": { "type": "object", "additionalProperties": true },
          "amountUsdc": { "type": "string" },
          "merchantAmountUsdc": { "type": "string" },
          "feeAmountUsdc": { "type": "string" },
          "checkoutUrl": { "type": "string", "format": "uri" },
          "solanaPayUrl": { "type": "string" },
          "buyerWalletAddress": { "type": ["string", "null"] },
          "transactionSignature": { "type": ["string", "null"] },
          "expiresAt": { "type": "string", "format": "date-time" },
          "confirmedAt": { "type": ["string", "null"], "format": "date-time" },
          "finalizedAt": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "Subscription": {
        "type": "object",
        "required": ["id", "customerEmail", "productId", "productName", "status", "entitled", "amountUsdc", "periodHours", "createdAt"],
        "properties": {
          "id": { "type": "string" },
          "customerEmail": { "type": "string", "format": "email" },
          "productId": { "type": "string" },
          "productName": { "type": "string" },
          "status": { "type": "string", "enum": ["authorization_pending", "activating", "active", "past_due", "cancel_pending", "cancelled", "revoked", "expired", "failed"] },
          "entitled": { "type": "boolean" },
          "amountUsdc": { "type": "string" },
          "periodHours": { "type": "integer" },
          "currentPeriodStart": { "type": ["string", "null"], "format": "date-time" },
          "currentPeriodEnd": { "type": ["string", "null"], "format": "date-time" },
          "nextChargeAt": { "type": ["string", "null"], "format": "date-time" },
          "cancelledAt": { "type": ["string", "null"], "format": "date-time" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "SubscriptionVerification": {
        "type": "object",
        "required": ["customerEmail", "status", "summary", "hasActiveSubscription", "hasMore", "page", "pageSize", "subscriptions"],
        "properties": {
          "customerEmail": { "type": ["string", "null"], "format": "email" },
          "productId": { "type": ["string", "null"] },
          "status": { "type": "string", "enum": ["authorization_pending", "activating", "active", "past_due", "cancel_pending", "cancelled", "revoked", "expired", "failed", "all"] },
          "summary": { "$ref": "#/components/schemas/SubscriptionSummary" },
          "hasActiveSubscription": { "type": "boolean" },
          "hasMore": { "type": "boolean" },
          "page": { "type": "integer" },
          "pageSize": { "type": "integer" },
          "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }
        }
      },
      "SubscriptionSummary": {
        "type": "object",
        "required": ["total", "authorizationPending", "activating", "active", "pastDue", "cancelPending", "cancelled", "revoked", "expired", "failed", "entitled", "mrrUsdc"],
        "properties": {
          "total": { "type": "integer", "minimum": 0 },
          "authorizationPending": { "type": "integer", "minimum": 0 },
          "activating": { "type": "integer", "minimum": 0 },
          "active": { "type": "integer", "minimum": 0 },
          "pastDue": { "type": "integer", "minimum": 0 },
          "cancelPending": { "type": "integer", "minimum": 0 },
          "cancelled": { "type": "integer", "minimum": 0 },
          "revoked": { "type": "integer", "minimum": 0 },
          "expired": { "type": "integer", "minimum": 0 },
          "failed": { "type": "integer", "minimum": 0 },
          "entitled": { "type": "integer", "minimum": 0 },
          "mrrUsdc": { "type": "string" }
        }
      },
      "Order": {
        "type": "object",
        "required": ["id", "customerEmail", "productId", "productName", "status", "amountUsdc", "merchantAmountUsdc", "feeAmountUsdc", "createdAt"],
        "properties": {
          "id": { "type": "string" },
          "customerEmail": { "type": "string", "format": "email" },
          "productId": { "type": "string" },
          "productName": { "type": "string" },
          "status": { "type": "string", "enum": ["pending", "processing", "paid", "expired", "failed"] },
          "amountUsdc": { "type": "string" },
          "merchantAmountUsdc": { "type": "string" },
          "feeAmountUsdc": { "type": "string" },
          "transactionSignature": { "type": ["string", "null"] },
          "createdAt": { "type": "string", "format": "date-time" },
          "confirmedAt": { "type": ["string", "null"], "format": "date-time" },
          "finalizedAt": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "OrderVerification": {
        "type": "object",
        "required": ["customerEmail", "status", "hasPaidOrder", "hasMore", "page", "pageSize", "orders"],
        "properties": {
          "customerEmail": { "type": "string", "format": "email" },
          "productId": { "type": ["string", "null"] },
          "status": { "type": "string" },
          "hasPaidOrder": { "type": "boolean" },
          "hasMore": { "type": "boolean" },
          "page": { "type": "integer" },
          "pageSize": { "type": "integer" },
          "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }
        }
      }
    }
  }
}