{ "openapi": "3.0.0", "paths": { "/v1/health": { "get": { "operationId": "HealthUiController_check", "summary": "Basic health check", "description": "Performs a basic health check to verify the service is running.", "parameters": [], "responses": { "200": { "description": "The Health Check is successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "info": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "error": { "type": "object", "example": {}, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "details": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true } } } } } } }, "503": { "description": "The Health Check is not successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "info": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "error": { "type": "object", "example": { "redis": { "status": "down", "message": "Could not connect" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "details": { "type": "object", "example": { "database": { "status": "up" }, "redis": { "status": "down", "message": "Could not connect" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true } } } } } } } }, "tags": [ "Health" ] } }, "/v1/health/build": { "get": { "operationId": "HealthUiController_getBuildInfo", "summary": "Build info", "description": "Returns build metadata for verifying which version is currently running. Dependency-free.", "parameters": [], "responses": { "200": { "description": "Build info retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "buildSha": { "type": "string", "example": "abc1234" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } }, "tags": [ "Health" ] } }, "/v1/health/detailed": { "get": { "operationId": "HealthUiController_getDetailedHealth", "summary": "Detailed health check", "description": "Performs a comprehensive health check including database connectivity, external services, and system metrics.", "parameters": [], "responses": { "200": { "description": "Detailed health status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "healthy" }, "timestamp": { "type": "string", "format": "date-time" }, "services": { "type": "object" }, "database": { "type": "object" }, "memory": { "type": "object" }, "uptime": { "type": "number" } } } } } } }, "tags": [ "Health" ] } }, "/v1/ui/files/download/*": { "get": { "operationId": "FileDownloadUiController_downloadFile", "summary": "Download file", "description": "Downloads a file by storage key. Requires authentication and appropriate permissions based on file metadata.", "parameters": [ { "name": "0", "required": true, "in": "path", "description": "Storage key (path) for the file to download", "schema": { "type": "string" } } ], "responses": { "200": { "description": "File stream", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Access denied to this file" }, "404": { "description": "File not found" } }, "tags": [ "File Downloads" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/files/mcp-server-avatar/*": { "get": { "operationId": "FileDownloadUiController_downloadMcpServerAvatar", "summary": "Download MCP server avatar", "description": "Downloads an MCP server avatar image by storage key. This endpoint verifies the file belongs to an MCP server avatar.", "parameters": [ { "name": "0", "required": true, "in": "path", "description": "Storage key (path) for the MCP server avatar to download", "schema": { "type": "string" } } ], "responses": { "200": { "description": "MCP server avatar image stream", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Access denied - file is not an MCP server avatar" }, "404": { "description": "File not found" } }, "tags": [ "File Downloads" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/files/public/*": { "get": { "operationId": "FileDownloadUiController_downloadPublicBrandingAsset", "summary": "Download public hosted branding asset", "description": "Downloads a publicly-readable hosted branding asset. Limited to provider logo files only.", "parameters": [ { "name": "0", "required": true, "in": "path", "description": "Storage key (path) for the public branding file", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public branding file stream", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "This file is not publicly readable" }, "404": { "description": "File not found" } }, "tags": [ "File Downloads" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/analytics/track": { "post": { "operationId": "AnalyticsUiController_trackEvent", "summary": "Track analytics event", "description": "Tracks an analytics event and sends relevant notifications to Slack based on event type.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackAnalyticsEventDto" } } } }, "responses": { "200": { "description": "Event tracked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } } }, "tags": [ "Analytics" ] } }, "/v1/ui/notifications": { "get": { "operationId": "NotificationUiController_getUserNotifications", "summary": "Get user notifications", "description": "Retrieves notifications for the authenticated user with optional filtering and pagination.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of notifications to return", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of notifications to skip for pagination", "schema": { "type": "number" } }, { "name": "isRead", "required": false, "in": "query", "description": "Filter by read status", "schema": { "type": "boolean" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by notification type", "schema": { "enum": [ "info", "success", "warning", "error", "payment", "transaction", "system" ], "type": "string" } }, { "name": "priority", "required": false, "in": "query", "description": "Filter by notification priority", "schema": { "enum": [ "low", "medium", "high", "urgent" ], "type": "string" } }, { "name": "includeArchived", "required": false, "in": "query", "description": "Include archived notifications", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Notifications retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Notification ID" }, "title": { "type": "string", "description": "Notification title" }, "message": { "type": "string", "description": "Notification message" }, "type": { "type": "string", "enum": [ "info", "success", "warning", "error", "payment", "transaction", "system" ], "description": "Notification type" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "description": "Notification priority" }, "isRead": { "type": "boolean", "description": "Whether notification is read" }, "isArchived": { "type": "boolean", "description": "Whether notification is archived" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } } } } } }, "401": { "description": "Unauthorized - invalid or missing authentication token" } }, "tags": [ "Notifications" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "NotificationUiController_createNotification", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationZodDto" } } } }, "responses": { "201": { "description": "" } }, "tags": [ "Notifications" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/notifications/stats": { "get": { "operationId": "NotificationUiController_getUserNotificationStats", "summary": "Get notification statistics", "description": "Retrieves comprehensive notification statistics for the authenticated user.", "parameters": [], "responses": { "200": { "description": "Notification statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of notifications" }, "unread": { "type": "number", "description": "Number of unread notifications" }, "read": { "type": "number", "description": "Number of read notifications" }, "archived": { "type": "number", "description": "Number of archived notifications" } } } } } }, "401": { "description": "Unauthorized - invalid or missing authentication token" } }, "tags": [ "Notifications" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/notifications/unread-count": { "get": { "operationId": "NotificationUiController_getUnreadCount", "summary": "Get unread notification count", "description": "Retrieves the count of unread notifications for the authenticated user.", "parameters": [], "responses": { "200": { "description": "Unread count retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number", "description": "Number of unread notifications" } } } } } }, "401": { "description": "Unauthorized - invalid or missing authentication token" } }, "tags": [ "Notifications" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/notifications/bulk": { "post": { "operationId": "NotificationUiController_createNotificationsForUsers", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreateNotificationDto" } } } }, "responses": { "201": { "description": "" } }, "tags": [ "Notifications" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "NotificationUiController_updateNotificationsBulk", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpdateNotificationDto" } } } }, "responses": { "204": { "description": "" } }, "tags": [ "Notifications" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/notifications/broadcast": { "post": { "operationId": "NotificationUiController_broadcastNotification", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastNotificationDto" } } } }, "responses": { "201": { "description": "" } }, "tags": [ "Notifications" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/notifications/{id}": { "put": { "operationId": "NotificationUiController_updateNotification", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNotificationDto" } } } }, "responses": { "204": { "description": "" } }, "tags": [ "Notifications" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/notifications/{id}/archive": { "put": { "operationId": "NotificationUiController_archiveNotification", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "" } }, "tags": [ "Notifications" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/notifications/cleanup": { "delete": { "operationId": "NotificationUiController_cleanupExpiredNotifications", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "Notifications" ], "security": [ { "bearer": [] } ] } }, "/v1/metrics": { "get": { "operationId": "MetricsUiController_getMetrics", "summary": "Get Prometheus metrics", "description": "Retrieves application metrics in Prometheus format for monitoring and observability.", "parameters": [], "responses": { "200": { "description": "Metrics retrieved successfully in Prometheus format", "content": { "text/plain": { "schema": { "type": "string", "example": "# HELP http_requests_total Total number of HTTP requests\n# TYPE http_requests_total counter\nhttp_requests_total{method=\"GET\",status=\"200\"} 100" } } } }, "500": { "description": "Internal server error while generating metrics" } }, "tags": [ "Metrics" ] } }, "/v1/metrics/json": { "get": { "operationId": "MetricsUiController_getMetricsAsJson", "summary": "Get metrics as JSON", "description": "Retrieves application metrics in JSON format for programmatic access and custom dashboards.", "parameters": [], "responses": { "200": { "description": "Metrics retrieved successfully in JSON format", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp when metrics were collected" }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Metric name" }, "value": { "type": "number", "description": "Metric value" }, "labels": { "type": "object", "description": "Metric labels" }, "type": { "type": "string", "description": "Metric type (counter, gauge, histogram)" } } } } } } } } }, "500": { "description": "Internal server error while generating metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" } } } } } } }, "tags": [ "Metrics" ] } }, "/v1/ui/activities": { "get": { "operationId": "ReferenceDataUiController_getActivities", "summary": "Get list of business activities", "description": "Returns a comprehensive list of industry standard business activities that can be used for main activity and additional activities selection.", "parameters": [], "responses": { "200": { "description": "List of business activities", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } } } } } } } }, "tags": [ "Reference Data" ] } }, "/v1/ui/fx/currencies": { "get": { "operationId": "FxUiController_getSupportedCurrencies", "summary": "Get list of supported currencies", "description": "Retrieves a comprehensive list of all supported currencies for foreign exchange operations and transactions.", "parameters": [], "responses": { "200": { "description": "List of supported currencies for transactions and exchange", "content": { "application/json": { "schema": { "type": "object", "properties": { "currencies": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Currency code (e.g., USD, EUR, GBP)" }, "name": { "type": "string", "description": "Full currency name" }, "symbol": { "type": "string", "description": "Currency symbol" }, "decimals": { "type": "number", "description": "Number of decimal places" }, "isActive": { "type": "boolean", "description": "Whether currency is currently active" } } } }, "count": { "type": "number", "description": "Total number of supported currencies" } } } } } }, "500": { "description": "Internal server error while retrieving currencies" } }, "tags": [ "FX" ] } }, "/v1/ui/providers": { "get": { "operationId": "ProviderUiController_getProvider", "summary": "Get provider information", "description": "Retrieves the current provider's information including verification status, settings, and environment switch availability.", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "ProviderUiController_updateProvider", "summary": "Update provider settings", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProviderUiDto" } } } }, "responses": { "200": { "description": "Provider updated successfully" }, "400": { "description": "Invalid request data" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/can-disconnect-stripe": { "get": { "operationId": "ProviderUiController_canDisconnectStripe", "summary": "Check whether Stripe can be disconnected", "description": "Returns whether the currently connected Stripe account can be disconnected without support intervention.", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/onboarding-start": { "post": { "operationId": "ProviderUiController_startOnboarding", "summary": "Start onboarding and provision Stripe account", "description": "Persists onboarding business details and provisions Stripe synchronously before allowing the onboarding flow to continue.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProviderUiDto" } } } }, "responses": { "200": { "description": "Onboarding saved and Stripe account provisioned" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/verifications": { "post": { "operationId": "ProviderUiController_submitForVerification", "summary": "Save provider data and start async verification", "description": "Saves provider data and starts verification in the background. Returns 202 Accepted immediately. Verification progress is sent via WebSocket events: verification:started, verification:progress, verification:completed", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProviderUiDto" } } } }, "responses": { "202": { "description": "Verification started in background" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/people/{personIndex}": { "delete": { "operationId": "ProviderUiController_deletePerson", "summary": "Delete a person from provider and sync to Stripe", "parameters": [ { "name": "personIndex", "required": true, "in": "path", "description": "Index of the person to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Person deleted successfully" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/environment": { "put": { "operationId": "ProviderUiController_switchEnvironment", "summary": "Switch provider environment", "description": "Switches the provider between sandbox and live environments. This is a critical operation that changes which data collections the provider can access.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchEnvironmentDto" } } } }, "responses": { "200": { "description": "Environment switched successfully" }, "400": { "description": "Bad request - invalid environment" }, "404": { "description": "Provider not found" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/stripe-account": { "delete": { "operationId": "ProviderUiController_disconnectStripeAccount", "summary": "Disconnect Stripe account", "description": "Disconnects the Stripe account from the provider. This clears the paymentProcessor field and allows connecting a different Stripe account.", "parameters": [], "responses": { "204": { "description": "Stripe account disconnected successfully" }, "404": { "description": "Provider not found" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/go-live-checklist": { "get": { "operationId": "ProviderUiController_getGoLiveChecklist", "summary": "Get the go-live checklist for this provider", "parameters": [], "responses": { "200": { "description": "Checklist returned" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/go-live": { "post": { "operationId": "ProviderUiController_goLive", "summary": "Switch provider to live mode (validates checklist)", "parameters": [], "responses": { "200": { "description": "Provider switched to live mode" }, "400": { "description": "Checklist requirements not met" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/reset-onboarding": { "post": { "operationId": "ProviderUiController_resetOnboarding", "summary": "Reset provider onboarding state (development only)", "description": "Resets tosAcceptance, verification, and status so the onboarding flow can be re-tested. Optionally deletes all products. Only available when NODE_ENV is not production.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetOnboardingDto" } } } }, "responses": { "200": { "description": "Onboarding reset successfully" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/documents": { "post": { "operationId": "ProviderDocumentUiController_uploadDocument", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "document": { "type": "string", "format": "binary" }, "documentType": { "type": "string", "description": "Type of document (e.g., \"identity\", \"business_license\", \"tax_certificate\")" }, "documentSide": { "type": "string", "enum": [ "front", "back" ], "description": "Side of the document (front or back)", "default": "front" } } } } } }, "responses": { "201": { "description": "" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "ProviderDocumentUiController_getDocuments", "summary": "Get provider documents", "parameters": [], "responses": { "200": { "description": "List of provider documents" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/documents/analyze": { "post": { "operationId": "ProviderDocumentUiController_analyzeDocument", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "document": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/documents/{documentId}": { "delete": { "operationId": "ProviderDocumentUiController_deleteDocument", "summary": "Delete a document", "parameters": [ { "name": "documentId", "required": true, "in": "path", "description": "ID of the document to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document deleted successfully" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/invitations": { "post": { "operationId": "ProviderInvitationUiController_createInvitations", "summary": "Create user invitations", "description": "Creates invitations for multiple users to join the provider. Sends invitation emails and stores invitation records.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationsDto" } } } }, "responses": { "201": { "description": "Invitations created successfully" }, "400": { "description": "Invalid request data" }, "404": { "description": "Provider not found" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "ProviderInvitationUiController_listInvitations", "summary": "List provider invitations", "description": "Lists all invitations for the current provider, sorted by most recent first.", "parameters": [], "responses": { "200": { "description": "Invitations retrieved successfully" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/invitations/{invitationId}": { "delete": { "operationId": "ProviderInvitationUiController_revokeInvitation", "summary": "Revoke an invitation", "description": "Cancels a pending invitation so it can no longer be accepted.", "parameters": [ { "name": "invitationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invitation revoked" }, "404": { "description": "Invitation not found" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/transfer-ownership": { "put": { "operationId": "ProviderUserUiController_transferOwnership", "summary": "Transfer provider ownership", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferOwnershipDto" } } } }, "responses": { "200": { "description": "Ownership transferred successfully" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/remove-user": { "put": { "operationId": "ProviderUserUiController_removeUser", "summary": "Remove user from provider", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveUserDto" } } } }, "responses": { "200": { "description": "User removed successfully" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/providers/update-user-role": { "put": { "operationId": "ProviderUserUiController_updateUserRole", "summary": "Update user role", "description": "Update a user's role in the provider. Admins can set admin/member. Only owner can promote to owner (transfers ownership).", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRoleDto" } } } }, "responses": { "200": { "description": "User role updated successfully" }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden" }, "404": { "description": "User or provider not found" } }, "tags": [ "Provider" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/providers": { "get": { "operationId": "AdminProviderUiController_getAllProviders", "summary": "Get all providers (Admin only)", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Search by provider name or email", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by provider status", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number (default 1)", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Results per page (default 50)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List of all providers" } }, "tags": [ "Admin - Providers" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "AdminProviderUiController_createProvider", "summary": "Create new provider (Admin only)", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProviderAdminDto" } } } }, "responses": { "201": { "description": "Provider created successfully" } }, "tags": [ "Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/providers/{providerRef}": { "get": { "operationId": "AdminProviderUiController_getProviderByReference", "summary": "Get provider by reference (Admin only)", "parameters": [ { "name": "providerRef", "required": true, "in": "path", "description": "Provider reference identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Provider details" } }, "tags": [ "Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/providers/{id}": { "put": { "operationId": "AdminProviderUiController_updateProvider", "summary": "Update provider (Admin only)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Provider ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProviderAdminDto" } } } }, "responses": { "200": { "description": "Provider updated successfully" } }, "tags": [ "Admin - Providers" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "AdminProviderUiController_deleteProvider", "summary": "Delete provider (Admin only)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Provider ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Provider deleted successfully" } }, "tags": [ "Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/providers/{id}/status": { "put": { "operationId": "AdminProviderUiController_updateProviderStatus", "summary": "Update provider status (Admin only)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Provider ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProviderStatusDto" } } } }, "responses": { "200": { "description": "Provider status updated successfully" } }, "tags": [ "Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/providers/{id}/users": { "get": { "operationId": "AdminProviderUiController_getProviderUsers", "summary": "Get provider users (Admin only)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Provider ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of provider users" } }, "tags": [ "Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/providers/{id}/transactions": { "get": { "operationId": "AdminProviderUiController_getProviderTransactions", "summary": "Get provider transactions (Admin only)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Provider ID", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Results per page", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List of provider transactions" } }, "tags": [ "Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/secret-keys": { "get": { "operationId": "SecretKeyUiController_getSecretKeys", "summary": "Get all secret keys", "description": "Retrieves all secret keys for the authenticated provider (both sandbox and live).", "parameters": [], "responses": { "200": { "description": "Secret keys retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "sandbox": { "type": "array", "items": { "type": "object" } }, "live": { "type": "array", "items": { "type": "object" } }, "liveEnabled": { "type": "boolean" }, "liveDisabledReason": { "type": "string" } } } } } }, "404": { "description": "Provider not found" } }, "tags": [ "Secret Keys" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "SecretKeyUiController_createSecretKey", "summary": "Create secret key", "description": "Creates a new secret key for the authenticated provider.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSecretKey" } } } }, "responses": { "201": { "description": "Secret key created successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Provider not found" } }, "tags": [ "Secret Keys" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/secret-keys/live-status": { "get": { "operationId": "SecretKeyUiController_getLiveStatus", "summary": "Check live eligibility", "description": "Check if the provider is eligible to create live secret keys.", "parameters": [], "responses": { "200": { "description": "Live eligibility status", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "reason": { "type": "string" } } } } } }, "404": { "description": "Provider not found" } }, "tags": [ "Secret Keys" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/secret-keys/stats/summary": { "get": { "operationId": "SecretKeyUiController_getSecretKeyStats", "summary": "Get secret key statistics", "description": "Retrieves statistics about secret key usage for the authenticated provider.", "parameters": [], "responses": { "200": { "description": "Secret key statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Provider not found" } }, "tags": [ "Secret Keys" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/secret-keys/{keyId}": { "delete": { "operationId": "SecretKeyUiController_deleteSecretKey", "summary": "Delete secret key", "description": "Permanently deletes a secret key.", "parameters": [ { "name": "keyId", "required": true, "in": "path", "description": "Secret key ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Secret key deleted successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Provider or secret key not found" } }, "tags": [ "Secret Keys" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/secret-keys/{keyId}/reveal": { "get": { "operationId": "SecretKeyUiController_revealSecretKey", "summary": "Reveal secret key", "description": "Retrieves the full secret key value. This is the only time the key will be shown.", "parameters": [ { "name": "keyId", "required": true, "in": "path", "description": "Secret key ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Secret key revealed successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Provider or secret key not found" } }, "tags": [ "Secret Keys" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/secret-keys/{keyId}/regenerate": { "post": { "operationId": "SecretKeyUiController_regenerateSecretKey", "summary": "Regenerate secret key", "description": "Regenerates a new secret key value, invalidating the old one.", "parameters": [ { "name": "keyId", "required": true, "in": "path", "description": "Secret key ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Secret key regenerated successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Provider or secret key not found" } }, "tags": [ "Secret Keys" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/users": { "get": { "operationId": "AdminUserUiController_getAllUsers", "summary": "Get all users (Admin only)", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Search term", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by user type", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List of all users", "content": { "application/json": { "schema": { "type": "object" } } } } }, "tags": [ "Admin - Users" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "AdminUserUiController_createUser", "summary": "Create new user (Admin only)", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserAdminDto" } } } }, "responses": { "201": { "description": "User created successfully", "content": { "application/json": { "schema": { "type": "object" } } } } }, "tags": [ "Admin - Users" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/users/stats": { "get": { "operationId": "AdminUserUiController_getUserStats", "summary": "Get user statistics (Admin only)", "parameters": [], "responses": { "200": { "description": "User statistics", "content": { "application/json": { "schema": { "type": "object" } } } } }, "tags": [ "Admin - Users" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/users/{id}": { "get": { "operationId": "AdminUserUiController_getUserById", "summary": "Get user by ID (Admin only)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User details", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "User not found" } }, "tags": [ "Admin - Users" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "AdminUserUiController_updateUser", "summary": "Update user (Admin only)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserAdminDto" } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "User not found" } }, "tags": [ "Admin - Users" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "AdminUserUiController_deleteUser", "summary": "Delete user (Admin only)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "User deleted successfully" }, "404": { "description": "User not found" } }, "tags": [ "Admin - Users" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/users/{id}/status": { "put": { "operationId": "AdminUserUiController_updateUserStatus", "summary": "Update user status (Admin only)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserStatusDto" } } } }, "responses": { "200": { "description": "User status updated successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "User not found" } }, "tags": [ "Admin - Users" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/users/{id}/provider": { "get": { "operationId": "AdminUserUiController_getUserProvider", "summary": "Get user provider (Admin only)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User provider details", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "User not found" } }, "tags": [ "Admin - Users" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/users/{id}/transactions": { "get": { "operationId": "AdminUserUiController_getUserTransactions", "summary": "Get user transactions (Admin only)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List of user transactions", "content": { "application/json": { "schema": { "type": "array" } } } }, "404": { "description": "User not found" } }, "tags": [ "Admin - Users" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/users/me": { "get": { "operationId": "AccountUiController_getMe", "summary": "Get current user profile", "parameters": [], "responses": { "200": { "description": "User profile retrieved successfully" }, "401": { "description": "Unauthorized" } }, "tags": [ "User Management" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "AccountUiController_deleteAccount", "summary": "Delete user account", "parameters": [], "responses": { "204": { "description": "Account deleted successfully" }, "401": { "description": "Unauthorized" } }, "tags": [ "User Management" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/users": { "put": { "operationId": "AccountUiController_updateUser", "summary": "Update user", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileZodDto" } } } }, "responses": { "200": { "description": "User updated successfully" }, "400": { "description": "Invalid data" }, "401": { "description": "Unauthorized" } }, "tags": [ "User Management" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/users/preferences": { "put": { "operationId": "AccountUiController_updatePreferences", "summary": "Update user preferences", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePreferencesZodDto" } } } }, "responses": { "200": { "description": "Preferences updated successfully" }, "400": { "description": "Invalid data" }, "401": { "description": "Unauthorized" } }, "tags": [ "User Management" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/users/emails/changes": { "post": { "operationId": "AccountUiController_requestEmailChange", "summary": "Request email change", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestEmailChangeZodDto" } } } }, "responses": { "200": { "description": "Email change verification sent" }, "400": { "description": "Email already in use" }, "401": { "description": "Unauthorized" } }, "tags": [ "User Management" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/users/emails/changes/verify": { "post": { "operationId": "AccountUiController_verifyEmailChange", "summary": "Verify email change with code", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailChangeZodDto" } } } }, "responses": { "200": { "description": "Email updated successfully" }, "400": { "description": "Invalid or expired code" }, "401": { "description": "Unauthorized" } }, "tags": [ "User Management" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/payment-intents": { "post": { "operationId": "PaymentIntentUiController_createPaymentIntent", "summary": "Create a payment intent", "description": "Creates a new payment intent for a plan purchase. Requires an idempotency key in the request header.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique idempotency key for the request", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentIntentDto" } } } }, "responses": { "201": { "description": "Payment intent created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "clientSecret": { "type": "string" }, "publishableKey": { "type": "string" }, "accountId": { "type": "string" } } } } } }, "400": { "description": "Bad request - missing required fields or idempotency key" } }, "tags": [ "Payments" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/payment-intents/{id}": { "get": { "operationId": "PaymentIntentUiController_getPaymentIntent", "summary": "Get a payment intent by id", "description": "Retrieves payment intent details by ID. Only returns payment intents belonging to the authenticated provider.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Payment intent ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment intent retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "clientSecret": { "type": "string" } } } } } }, "400": { "description": "Invalid payment intent ID" }, "404": { "description": "Payment intent not found" } }, "tags": [ "Payments" ], "security": [ { "bearer": [] } ] } }, "/v1/checkout-sessions/{sessionId}": { "get": { "operationId": "CheckoutSessionPublicController_getCheckoutSessionBySessionId", "summary": "Get a checkout session by sessionId (public)", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Checkout session ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkout session retrieved successfully" }, "404": { "description": "Checkout session not found or expired" } }, "tags": [ "Payments" ] } }, "/v1/checkout-sessions/{sessionId}/plans": { "get": { "operationId": "CheckoutSessionPublicController_getPlansForSession", "summary": "Get available plans for a checkout session (public)", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Checkout session ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of available plans with reference, price, currency, billingCycle, and planType" }, "400": { "description": "Product reference or provider ID not found in session" }, "404": { "description": "Checkout session not found" } }, "tags": [ "Payments" ] } }, "/v1/checkout-sessions/{sessionId}/select-plan": { "post": { "operationId": "CheckoutSessionPublicController_updateSessionPlan", "summary": "Select a plan for a checkout session and create payment intent (public)", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Checkout session ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCheckoutSessionPlanDto" } } } }, "responses": { "200": { "description": "Plan selected and payment intent created successfully" }, "400": { "description": "Invalid request or plan already selected" }, "404": { "description": "Checkout session, product, or plan not found" } }, "tags": [ "Payments" ] } }, "/v1/checkout-sessions/{sessionId}/select-topup-amount": { "post": { "operationId": "CheckoutSessionPublicController_selectTopupAmount", "summary": "Select a topup amount for a checkout session and create payment intent (public)", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Checkout session ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectTopupAmountDto" } } } }, "responses": { "200": { "description": "Topup amount selected and payment intent created" }, "400": { "description": "Invalid request" }, "404": { "description": "Checkout session not found" } }, "tags": [ "Payments" ] } }, "/v1/checkout-sessions/{sessionId}/reset-plan": { "post": { "operationId": "CheckoutSessionPublicController_resetSessionPlan", "summary": "Reset selected plan for checkout session and cancel payment intent (public)", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Checkout session ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Selected plan reset and payment intent cancelled successfully" }, "400": { "description": "Invalid checkout session state" }, "404": { "description": "Checkout session not found" } }, "tags": [ "Payments" ] } }, "/v1/ui/checkout-sessions/{id}": { "get": { "operationId": "CheckoutSessionUiController_getCheckoutSession", "summary": "Get a payment session by id or sessionId", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Payment session ID or sessionId", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment session retrieved successfully" }, "404": { "description": "Payment session not found or expired" } }, "tags": [ "Payments" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/checkout-sessions": { "post": { "operationId": "CheckoutSessionUiController_createCheckoutSession", "summary": "Create a checkout session for a customer", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionRequest" } } } }, "responses": { "201": { "description": "Checkout session created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUiCheckoutSessionResponse" } } } }, "400": { "description": "Invalid request parameters" }, "404": { "description": "Customer, product, or plan not found" } }, "tags": [ "Payments" ], "security": [ { "bearer": [] } ] } }, "/v1/customer-sessions/{sessionId}": { "get": { "operationId": "CustomerSessionManageUiController_getCustomerSession", "summary": "Get customer session", "description": "Retrieves customer session details including customer information and purchases.", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Customer session ID", "schema": { "example": "9a12833f942007f39e0ea3713e3a75fd", "type": "string" } } ], "responses": { "200": { "description": "Customer session retrieved successfully" }, "404": { "description": "Customer session not found" } }, "tags": [ "Customer Sessions" ] } }, "/v1/customer-sessions/{sessionId}/select-product": { "post": { "operationId": "CustomerSessionUiController_selectCustomerSessionProduct", "summary": "Switch selected product for a customer session (public)", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Customer session ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectCustomerSessionProductDto" } } } }, "responses": { "200": { "description": "Customer session updated and hydrated for selected product" }, "400": { "description": "Invalid request body" }, "404": { "description": "Customer session or product not found" } }, "tags": [ "Payments" ] } }, "/v1/customer-sessions/{sessionId}/upgrade-checkout": { "post": { "operationId": "CustomerSessionManageUiController_createUpgradeCheckout", "summary": "Create an upgrade checkout session", "description": "Creates a checkout session for the selected product in this customer session and returns a checkout URL.", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Customer session ID", "schema": { "example": "9a12833f942007f39e0ea3713e3a75fd", "type": "string" } } ], "responses": { "200": { "description": "Upgrade checkout session created successfully" }, "400": { "description": "Customer session does not contain required upgrade context" }, "404": { "description": "Customer session not found" } }, "tags": [ "Customer Sessions" ] } }, "/v1/customer-sessions/{sessionId}/topup-checkout": { "post": { "operationId": "CustomerSessionManageUiController_createTopupCheckout", "summary": "Create a credit top-up checkout session", "description": "Creates a checkout session for topping up the customer credit balance and returns a checkout URL.", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Customer session ID", "schema": { "example": "9a12833f942007f39e0ea3713e3a75fd", "type": "string" } } ], "responses": { "200": { "description": "Top-up checkout session created successfully" }, "400": { "description": "Customer session does not contain required context" }, "404": { "description": "Customer session not found" } }, "tags": [ "Customer Sessions" ] } }, "/v1/customer-sessions/{sessionId}/plans": { "get": { "operationId": "CustomerSessionManageUiController_getSelectedProductPlans", "summary": "Get eligible plans for selected product in customer session", "description": "Returns selectable pricing options for the selected product in this customer session without creating a checkout session.", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Customer session ID", "schema": { "example": "9a12833f942007f39e0ea3713e3a75fd", "type": "string" } } ], "responses": { "200": { "description": "Eligible plans retrieved successfully" }, "400": { "description": "Selected product or provider context missing from session" }, "404": { "description": "Customer session not found" } }, "tags": [ "Customer Sessions" ] } }, "/v1/customer-sessions/{sessionId}/select-plan": { "post": { "operationId": "CustomerSessionManageUiController_selectPlanAndCreateCheckout", "summary": "Create checkout session from selected customer-session plan", "description": "Creates a checkout session for the selected product, applies the selected plan, and returns checkout URL.", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Customer session ID", "schema": { "example": "9a12833f942007f39e0ea3713e3a75fd", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCheckoutSessionPlanDto" } } } }, "responses": { "200": { "description": "Checkout session created and plan selected successfully" }, "400": { "description": "Invalid session context or plan selection request" }, "404": { "description": "Customer session not found" } }, "tags": [ "Customer Sessions" ] } }, "/v1/customer-sessions/{sessionId}/purchases/{purchaseRef}/cancel-renewal": { "post": { "operationId": "CustomerSessionManageUiController_cancelRenewal", "summary": "Cancel renewal of a purchase", "description": "Cancels renewal of an active purchase using its reference ID. Validates that the purchase belongs to the customer in the session.", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Customer session ID", "schema": { "example": "9a12833f942007f39e0ea3713e3a75fd", "type": "string" } }, { "name": "purchaseRef", "required": true, "in": "path", "description": "Purchase reference identifier", "schema": { "example": "sub_Q2P5R8JX", "type": "string" } } ], "requestBody": { "required": false, "description": "Cancellation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPurchaseRequest" } } } }, "responses": { "200": { "description": "Renewal cancelled successfully" }, "400": { "description": "Renewal cannot be cancelled or purchase does not belong to customer" }, "404": { "description": "Session or purchase not found" } }, "tags": [ "Customer Sessions" ] } }, "/v1/customer-sessions/{sessionId}/purchases/{purchaseRef}/reactivate": { "post": { "operationId": "CustomerSessionManageUiController_reactivatePurchase", "summary": "Reactivate a cancelled purchase", "description": "Reactivates a purchase that was cancelled but has not yet reached its end date. This removes the cancellation and restores auto-renewal if applicable.", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Customer session ID", "schema": { "example": "9a12833f942007f39e0ea3713e3a75fd", "type": "string" } }, { "name": "purchaseRef", "required": true, "in": "path", "description": "Purchase reference identifier", "schema": { "example": "sub_Q2P5R8JX", "type": "string" } } ], "responses": { "200": { "description": "Purchase reactivated successfully" }, "400": { "description": "Purchase cannot be reactivated" }, "404": { "description": "Session or purchase not found" } }, "tags": [ "Customer Sessions" ] } }, "/v1/sdk/payment-intents": { "post": { "operationId": "PaymentIntentSdkController_createPaymentIntent", "summary": "Create a payment intent", "description": "Creates a new payment intent for a customer to purchase a plan. Requires an idempotency key to prevent duplicate charges. Returns client secret and publishable key needed for frontend integration.", "parameters": [ { "name": "idempotency-key", "required": true, "in": "header", "description": "Unique idempotency key to prevent duplicate payments (required)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Payment intent creation data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentIntentDto" } } } }, "responses": { "201": { "description": "Payment intent created successfully", "content": { "application/json": { "schema": { "example": { "processorPaymentId": "pi_1a2b3c4d5e6f7g8h", "planRef": "pln_2b3c4d5e6f7g", "customerRef": "cus_3c4d5e6f7g8h", "amount": 4999, "originalAmount": 4999, "currency": "usd", "exchangeRate": 1, "status": "requires_payment_method", "clientSecret": "pi_1a2b3c4d5e6f7g8h_secret_AbCdEf123456", "publishableKey": "pk_test_...", "expiresAt": "2025-10-19T10:30:00.000Z", "createdAt": "2025-10-18T10:30:00.000Z" } } } } }, "400": { "description": "Missing required fields or invalid data", "content": { "application/json": { "schema": { "example": { "statusCode": 400, "message": "idempotency-key header is required", "error": "Bad Request" } } } } } }, "tags": [ "Payment Intents" ], "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "PaymentIntentSdkController_getPaymentIntents", "summary": "List payment intents for the provider", "description": "Retrieves a paginated list of all payment intents created by the authenticated provider. Supports pagination through limit and offset query parameters.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of results", "schema": { "example": 50, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Pagination offset", "schema": { "example": 0, "type": "number" } } ], "responses": { "200": { "description": "Payment intents retrieved successfully", "content": { "application/json": { "schema": { "example": { "paymentIntents": [ { "processorPaymentId": "pi_1a2b3c4d5e6f7g8h", "planRef": "pln_2b3c4d5e6f7g", "amount": 4999, "currency": "usd", "clientSecret": "pi_1a2b3c4d5e6f7g8h_secret_xxx", "status": "succeeded", "createdAt": "2025-10-11T10:30:00.000Z" } ], "total": 1 } } } } } }, "tags": [ "Payment Intents" ], "security": [ { "SecretKey": [] } ] } }, "/v1/sdk/payment-intents/{reference}": { "get": { "operationId": "PaymentIntentSdkController_getPaymentIntent", "summary": "Get a specific payment intent", "description": "Retrieves detailed information about a specific payment intent including amount, currency, and client secret.", "parameters": [ { "name": "reference", "required": true, "in": "path", "description": "Payment intent reference or processor payment ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment intent retrieved successfully", "content": { "application/json": { "schema": { "example": { "planRef": "pln_2b3c4d5e6f7g", "amount": 4999, "currency": "usd", "clientSecret": "pi_1a2b3c4d5e6f7g8h_secret_xxx" } } } } }, "404": { "description": "Payment intent not found", "content": { "application/json": { "schema": { "example": { "success": false, "error": "Payment intent not found", "code": "PAYMENT_INTENT_NOT_FOUND" } } } } } }, "tags": [ "Payment Intents" ], "security": [ { "SecretKey": [] } ] } }, "/v1/sdk/payment-intents/{processorPaymentId}/process": { "post": { "operationId": "PaymentIntentSdkController_processPaymentIntent", "summary": "Process payment intent after client-side confirmation", "description": "Processes a payment intent that has been confirmed on the client side. Polls the database for payment intent status to become succeeded (up to 10 seconds). Returns the current status of the payment intent.", "parameters": [ { "name": "processorPaymentId", "required": true, "in": "path", "description": "Payment processor ID returned from createPaymentIntent", "schema": { "example": "pi_1a2b3c4d5e6f7g8h", "type": "string" } } ], "requestBody": { "required": true, "description": "Payment processing data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessPaymentIntentDto" } } } }, "responses": { "200": { "description": "Payment intent status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "succeeded", "timeout", "failed", "cancelled" ], "description": "Payment intent status", "example": "succeeded" }, "message": { "type": "string", "description": "Optional message, only present for timeout status", "example": "Timeout while waiting for payment intent confirmation, try again later. This could be due to payment webhooks not being configured correctly." } }, "examples": { "succeeded": { "value": { "status": "succeeded" }, "description": "Payment intent confirmed successfully" }, "timeout": { "value": { "status": "timeout", "message": "Timeout while waiting for payment intent confirmation, try again later. This could be due to payment webhooks not being configured correctly." }, "description": "Timeout waiting for payment intent confirmation" }, "failed": { "value": { "status": "failed" }, "description": "Payment intent failed" }, "cancelled": { "value": { "status": "cancelled" }, "description": "Payment intent cancelled" } } } } } }, "400": { "description": "Payment not succeeded, invalid request, or forbidden", "content": { "application/json": { "schema": { "example": { "statusCode": 400, "message": "Payment not succeeded. Status: requires_payment_method", "error": "Bad Request" } } } } } }, "tags": [ "Payment Intents" ], "security": [ { "SecretKey": [] } ] } }, "/v1/ui/connected-accounts/{providerId}/requirements": { "get": { "operationId": "StripeUiController_getAccountRequirements", "summary": "Get account requirements for a provider", "parameters": [ { "name": "providerId", "required": true, "in": "path", "description": "The provider ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account requirements retrieved successfully" }, "404": { "description": "Provider not found" } }, "tags": [ "Stripe" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/connected-accounts/payout-schedule": { "put": { "operationId": "StripeUiController_updatePayoutSchedule", "summary": "Update payout schedule for the authenticated provider", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePayoutScheduleDto" } } } }, "responses": { "200": { "description": "Payout schedule updated successfully" }, "400": { "description": "Invalid schedule configuration" }, "404": { "description": "Provider not found for user" } }, "tags": [ "Stripe" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/connected-accounts/{providerId}": { "put": { "operationId": "StripeUiController_updateConnectedAccount", "summary": "Update a connected Stripe account", "parameters": [ { "name": "providerId", "required": true, "in": "path", "description": "The provider ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConnectedAccountDto" } } } }, "responses": { "200": { "description": "Connected account updated successfully" }, "404": { "description": "Provider not found" } }, "tags": [ "Stripe" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/connected-accounts": { "get": { "operationId": "StripeUiController_getMyConnectedAccount", "summary": "Get the connected account for the authenticated user", "parameters": [], "responses": { "200": { "description": "Connected account details retrieved successfully" }, "404": { "description": "Provider not found" } }, "tags": [ "Stripe" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/connected-accounts/statuses": { "get": { "operationId": "StripeUiController_getMyAccountStatus", "summary": "Get account status for the authenticated user", "parameters": [], "responses": { "200": { "description": "Account status retrieved successfully" }, "404": { "description": "Provider not found" } }, "tags": [ "Stripe" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/connected-accounts/payments": { "post": { "operationId": "StripeUiController_createPayment", "summary": "Create a payment intent for the authenticated provider", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStripePaymentDto" } } } }, "responses": { "201": { "description": "Payment intent created successfully" }, "400": { "description": "Invalid payment data" }, "404": { "description": "Provider not found" } }, "tags": [ "Stripe" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/connected-accounts/payout-settings": { "get": { "operationId": "StripeUiController_getPayoutSettings", "summary": "Get payout settings for the authenticated provider", "parameters": [], "responses": { "200": { "description": "Payout settings retrieved successfully" }, "404": { "description": "Provider not found for user" } }, "tags": [ "Stripe" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/connected-accounts/manual-payout": { "post": { "operationId": "StripeUiController_createManualPayout", "summary": "Create a manual payout for the authenticated provider", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManualPayoutDto" } } } }, "responses": { "201": { "description": "Manual payout created successfully" }, "400": { "description": "Invalid payout data" }, "404": { "description": "Provider not found for user" } }, "tags": [ "Stripe" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/connected-accounts/payouts": { "get": { "operationId": "StripeUiController_getPayoutHistory", "summary": "Get payout history for the authenticated provider", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of payouts to return (default 20)", "schema": { "type": "number" } }, { "name": "starting_after", "required": false, "in": "query", "description": "Cursor for pagination (payout ID)", "schema": { "type": "string" } }, { "name": "source", "required": false, "in": "query", "description": "Payout source filter: solvapay (default) or all", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payout history retrieved successfully" }, "404": { "description": "Provider not found for user" } }, "tags": [ "Stripe" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/connected-accounts/{providerId}/payouts": { "get": { "operationId": "StripeUiController_getPayoutHistoryAdmin", "summary": "Get payout history for a provider (admin)", "parameters": [ { "name": "providerId", "required": true, "in": "path", "description": "The provider ID", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of payouts to return (default 20)", "schema": { "type": "number" } }, { "name": "starting_after", "required": false, "in": "query", "description": "Cursor for pagination (payout ID)", "schema": { "type": "string" } }, { "name": "source", "required": false, "in": "query", "description": "Payout source filter: all (default) or solvapay", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payout history retrieved successfully" } }, "tags": [ "Stripe" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/connected-accounts/{providerId}/account-links": { "post": { "operationId": "StripeUiController_createAccountLink", "summary": "Create a Stripe account onboarding link", "parameters": [ { "name": "providerId", "required": true, "in": "path", "description": "The provider ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountLinkDto" } } } }, "responses": { "201": { "description": "Account link created successfully" }, "404": { "description": "Provider not found" } }, "tags": [ "Stripe" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/connected-accounts/{providerId}/status": { "get": { "operationId": "StripeUiController_getAccountStatus", "summary": "Get account status for a provider", "parameters": [ { "name": "providerId", "required": true, "in": "path", "description": "The provider ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account status retrieved successfully" }, "404": { "description": "Provider not found" } }, "tags": [ "Stripe" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/stripe/oauth/authorize": { "post": { "operationId": "StripeOAuthUiController_createAuthorizationUrl", "summary": "Create OAuth authorization URL", "description": "Creates a Stripe OAuth authorization URL to link an existing Stripe account.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeOAuthAuthorizeDto" } } } }, "responses": { "200": { "description": "Authorization URL created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "authUrl": { "type": "string" } } } } } } }, "tags": [ "Stripe OAuth" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/stripe/oauth/callback": { "post": { "operationId": "StripeOAuthUiController_exchangeAuthorizationCode", "summary": "Exchange authorization code", "description": "Exchanges the OAuth authorization code to link the Stripe account.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeOAuthCallbackDto" } } } }, "responses": { "200": { "description": "Stripe account linked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" }, "source": { "type": "string" } } } } } } }, "tags": [ "Stripe OAuth" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/checkout-sessions": { "post": { "operationId": "CheckoutSessionSdkController_createCheckoutSession", "summary": "Create a checkout session", "description": "Creates a hosted checkout session for a customer to purchase a product plan. Returns a session ID and checkout URL for redirect.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionRequest" } } } }, "responses": { "201": { "description": "Checkout session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionResponse" } } } }, "400": { "description": "Missing customerRef or productRef" } }, "tags": [ "Checkout Sessions" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/provider/auth/signups": { "post": { "operationId": "ProviderUiAuthController_signup", "summary": "Sign up a new user", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupDto" } } } }, "responses": { "201": { "description": "User signed up successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "Bad request - validation error or user already exists" } }, "tags": [ "Provider Auth" ] } }, "/v1/ui/provider/auth/logins": { "post": { "operationId": "ProviderUiAuthController_requestLoginCode", "summary": "Request a login code sent to email", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginDto" } } } }, "responses": { "200": { "description": "Login code sent (if account exists)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } }, "tags": [ "Provider Auth" ] } }, "/v1/ui/provider/auth/logins/verifications": { "post": { "operationId": "ProviderUiAuthController_verifyLoginCode", "summary": "Verify a login code and receive JWT tokens", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyLoginCodeDto" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "Validation error" }, "401": { "description": "Invalid or expired code" } }, "tags": [ "Provider Auth" ] } }, "/v1/ui/provider/auth/logins/resends": { "post": { "operationId": "ProviderUiAuthController_resendLoginCode", "summary": "Resend a login code (rate-limited)", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginDto" } } } }, "responses": { "200": { "description": "Login code resent", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Rate limit exceeded" } }, "tags": [ "Provider Auth" ] } }, "/v1/ui/provider/auth/two-factor-setups": { "post": { "operationId": "ProviderUiAuthController_initiateTwoFactorSetup", "summary": "Initiate optional 2FA setup (requires JWT)", "parameters": [], "responses": { "200": { "description": "2FA setup initiated (returns secret, QR code, backup codes)" }, "401": { "description": "Unauthorized" }, "404": { "description": "User not found" } }, "tags": [ "Provider Auth" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/provider/auth/two-factor-verifications": { "post": { "operationId": "ProviderUiAuthController_verifyTwoFactorSetup", "summary": "Verify TOTP token to complete 2FA setup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwoFactorTokenDto" } } } }, "responses": { "200": { "description": "2FA enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } } } } } }, "400": { "description": "Invalid token or 2FA already enabled" }, "401": { "description": "Unauthorized" } }, "tags": [ "Provider Auth" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/provider/auth/logouts": { "post": { "operationId": "ProviderUiAuthController_logout", "summary": "Logout user", "parameters": [], "responses": { "200": { "description": "Logout successful" }, "401": { "description": "Unauthorized" } }, "tags": [ "Provider Auth" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/provider/auth/email-verifications": { "post": { "operationId": "ProviderUiAuthController_verifyEmail", "summary": "Verify email", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailDto" } } } }, "responses": { "200": { "description": "Email verified successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "Invalid or expired code" } }, "tags": [ "Provider Auth" ] } }, "/v1/ui/provider/auth/email-verifications/resends": { "post": { "operationId": "ProviderUiAuthController_resendEmailVerificationCode", "summary": "Resend verification code", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginDto" } } } }, "responses": { "200": { "description": "Verification code sent" }, "400": { "description": "Email already verified" } }, "tags": [ "Provider Auth" ] } }, "/v1/ui/provider/auth/invitations/{token}": { "get": { "operationId": "ProviderUiAuthController_getInvitationByToken", "summary": "Get invitation details by token", "parameters": [ { "name": "token", "required": true, "in": "path", "description": "Invitation token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invitation details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string" }, "providerName": { "type": "string" } } } } } }, "404": { "description": "Invitation not found or expired" } }, "tags": [ "Provider Auth" ] } }, "/v1/ui/provider/auth/accepted-invites": { "post": { "operationId": "ProviderUiAuthController_acceptInvite", "summary": "Accept user invitation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "inviteCode", "name" ], "properties": { "inviteCode": { "type": "string", "description": "Invitation token" }, "email": { "type": "string", "format": "email", "description": "Email address (for verification)" }, "name": { "type": "string", "description": "Full name" } } } } } }, "responses": { "200": { "description": "Invitation accepted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "Invalid or expired invitation token" } }, "tags": [ "Provider Auth" ] } }, "/v1/ui/provider/auth/google": { "get": { "operationId": "ProviderUiAuthController_googleAuth", "summary": "Initiate Google OAuth login", "parameters": [ { "name": "returnTo", "required": false, "in": "query", "description": "URL path to return to after auth", "schema": {} }, { "name": "inviteToken", "required": false, "in": "query", "description": "Invitation token for invite flow", "schema": {} }, { "name": "flowType", "required": false, "in": "query", "schema": { "enum": [ "login", "signup", "invite", "cli_init" ], "type": "string" } } ], "responses": { "302": { "description": "Redirect to Google OAuth" } }, "tags": [ "Provider Auth" ] } }, "/v1/ui/provider/auth/google/callback": { "get": { "operationId": "ProviderUiAuthController_googleAuthCallback", "summary": "Google OAuth callback", "parameters": [], "responses": { "302": { "description": "Redirect to frontend with auth result" } }, "tags": [ "Provider Auth" ] } }, "/v1/ui/provider/auth/google/session-logins": { "post": { "operationId": "ProviderUiAuthController_googleSessionLogin", "summary": "Create session from Google OAuth", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginDto" } } } }, "responses": { "200": { "description": "Session created with tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "Email is required or user not found" }, "403": { "description": "Google OAuth not enabled for this user" } }, "tags": [ "Provider Auth" ] } }, "/v1/ui/provider/auth/github": { "get": { "operationId": "ProviderUiAuthController_githubAuth", "summary": "Initiate GitHub OAuth login", "parameters": [ { "name": "returnTo", "required": false, "in": "query", "description": "URL path to return to after auth", "schema": {} }, { "name": "inviteToken", "required": false, "in": "query", "description": "Invitation token for invite flow", "schema": {} }, { "name": "flowType", "required": false, "in": "query", "schema": { "enum": [ "login", "signup", "invite", "cli_init" ], "type": "string" } } ], "responses": { "302": { "description": "Redirect to GitHub OAuth" } }, "tags": [ "Provider Auth" ] } }, "/v1/ui/provider/auth/github/callback": { "get": { "operationId": "ProviderUiAuthController_githubAuthCallback", "summary": "GitHub OAuth callback", "parameters": [], "responses": { "302": { "description": "Redirect to frontend with auth result" } }, "tags": [ "Provider Auth" ] } }, "/v1/ui/provider/auth/github/session-logins": { "post": { "operationId": "ProviderUiAuthController_githubSessionLogin", "summary": "Create session from GitHub OAuth", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginDto" } } } }, "responses": { "200": { "description": "Session created with tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "Email is required or user not found" }, "403": { "description": "GitHub OAuth not enabled for this user" } }, "tags": [ "Provider Auth" ] } }, "/v1/mcp/provider/auth/google": { "get": { "operationId": "ProviderMcpAuthController_googleAuth", "summary": "MCP Google OAuth initiation", "parameters": [ { "name": "returnTo", "required": false, "in": "query", "description": "Relative path to redirect after auth", "schema": {} } ], "responses": { "302": { "description": "Redirects to Google OAuth consent screen" } }, "tags": [ "Provider MCP Auth" ] } }, "/v1/mcp/provider/auth/google/callback": { "get": { "operationId": "ProviderMcpAuthController_googleCallback", "summary": "MCP Google OAuth callback", "parameters": [], "responses": { "302": { "description": "Redirect to frontend" } }, "tags": [ "Provider MCP Auth" ] } }, "/v1/mcp/provider/auth/google/sessions": { "post": { "operationId": "ProviderMcpAuthController_googleSession", "summary": "Create MCP session from Google OAuth", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "401": { "description": "User not found or OAuth provider mismatch" } }, "tags": [ "Provider MCP Auth" ] } }, "/v1/mcp/provider/auth/github": { "get": { "operationId": "ProviderMcpAuthController_githubAuth", "summary": "MCP GitHub OAuth initiation", "parameters": [ { "name": "returnTo", "required": false, "in": "query", "description": "Relative path to redirect after auth", "schema": {} } ], "responses": { "302": { "description": "Redirects to GitHub OAuth consent screen" } }, "tags": [ "Provider MCP Auth" ] } }, "/v1/mcp/provider/auth/github/callback": { "get": { "operationId": "ProviderMcpAuthController_githubCallback", "summary": "MCP GitHub OAuth callback", "parameters": [], "responses": { "302": { "description": "Redirect to frontend" } }, "tags": [ "Provider MCP Auth" ] } }, "/v1/mcp/provider/auth/github/sessions": { "post": { "operationId": "ProviderMcpAuthController_githubSession", "summary": "Create MCP session from GitHub OAuth", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "401": { "description": "User not found or OAuth provider mismatch" } }, "tags": [ "Provider MCP Auth" ] } }, "/v1/customer/auth/public/client-info": { "get": { "operationId": "AuthorizationServerController_getClientInfo", "summary": "Get public client info for branding", "parameters": [ { "name": "client_id", "required": true, "in": "query", "description": "OAuth client ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Client branding info" }, "400": { "description": "Missing or invalid client_id" } }, "tags": [ "Customer OAuth Server" ] } }, "/v1/customer/auth/authorize": { "get": { "operationId": "AuthorizationServerController_authorize", "summary": "OAuth 2.0 authorization endpoint", "parameters": [ { "name": "client_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "redirect_uri", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "response_type", "required": true, "in": "query", "description": "Must be \"code\"", "schema": { "type": "string" } }, { "name": "scope", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "state", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "code_challenge", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "code_challenge_method", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "token", "required": false, "in": "query", "description": "Existing access token for silent re-authorization", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirects to login page or directly to redirect_uri with auth code" }, "400": { "description": "Missing parameters, invalid client, or invalid redirect_uri" } }, "tags": [ "Customer OAuth Server" ] } }, "/v1/customer/auth/register": { "post": { "operationId": "AuthorizationServerController_register", "summary": "OAuth 2.0 Dynamic Client Registration", "description": "Registers a new OAuth client dynamically (RFC 7591)", "parameters": [ { "name": "mcp_server_id", "required": false, "in": "query", "description": "Hosted MCP server identifier", "schema": { "type": "string" } }, { "name": "product_ref", "required": false, "in": "query", "description": "Non-hosted product reference", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamicClientRegistrationDto" } } } }, "responses": { "201": { "description": "Client registered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamicClientRegistrationResponseDto" } } } }, "400": { "description": "Invalid registration request" } }, "tags": [ "Customer OAuth Server" ] } }, "/v1/customer/auth/token": { "post": { "operationId": "AuthorizationServerController_token", "summary": "OAuth 2.0 token endpoint", "parameters": [ { "name": "authorization", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "content-type", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "user-agent", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequestDto" } } } }, "responses": { "200": { "description": "Access token issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "number" }, "refresh_token": { "type": "string" }, "scope": { "type": "string" } } } } } }, "400": { "description": "Invalid request, missing parameters, or bad grant" }, "401": { "description": "Invalid or inactive client credentials" } }, "tags": [ "Customer OAuth Server" ] } }, "/v1/customer/auth/userinfo": { "get": { "operationId": "AuthorizationServerController_userinfo", "summary": "OpenID Connect userinfo endpoint", "parameters": [ { "name": "authorization", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User information" }, "401": { "description": "Missing or invalid authorization header" } }, "tags": [ "Customer OAuth Server" ], "security": [ { "bearer": [] } ] } }, "/v1/customer/auth/revoke": { "post": { "operationId": "AuthorizationServerController_revoke", "summary": "Token revocation endpoint", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeTokenDto" } } } }, "responses": { "200": { "description": "Token revoked" }, "400": { "description": "Missing token" } }, "tags": [ "Customer OAuth Server" ] } }, "/v1/customer/auth/login-page": { "get": { "operationId": "LoginController_loginPage", "summary": "OAuth login page (Redirects to Frontend)", "parameters": [ { "name": "client_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "redirect_uri", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "scope", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "state", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "code_challenge", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "code_challenge_method", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "mcp_subdomain", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirects to frontend or custom login page" }, "400": { "description": "Missing required parameters or invalid client_id" } }, "tags": [ "Customer Auth" ] } }, "/v1/customer/auth/logins": { "post": { "operationId": "LoginController_handleLogin", "summary": "Handle OAuth login", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoginDto" } } } }, "responses": { "200": { "description": "Login successful, returns redirect URL with auth code", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectUrl": { "type": "string" } } } } } }, "400": { "description": "Missing required fields, invalid client, redirect_uri, or credentials" } }, "tags": [ "Customer Auth" ] } }, "/v1/customer/auth/google": { "get": { "operationId": "GoogleController_authorizeGoogle", "summary": "Initiate Google OAuth flow for Customers", "parameters": [ { "name": "client_id", "required": true, "in": "query", "description": "OAuth client ID", "schema": { "type": "string" } }, { "name": "redirect_uri", "required": true, "in": "query", "description": "Redirect URI after authorization", "schema": { "type": "string" } }, { "name": "state", "required": false, "in": "query", "description": "Opaque state value forwarded to the callback", "schema": { "type": "string" } }, { "name": "scope", "required": false, "in": "query", "description": "Space-separated OAuth scopes", "schema": { "type": "string" } }, { "name": "code_challenge", "required": false, "in": "query", "description": "PKCE code challenge", "schema": { "type": "string" } }, { "name": "code_challenge_method", "required": false, "in": "query", "description": "PKCE method (S256)", "schema": { "type": "string" } }, { "name": "mcp_subdomain", "required": false, "in": "query", "description": "MCP server subdomain", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirects to Google consent screen" }, "400": { "description": "Missing client_id/redirect_uri or invalid client" } }, "tags": [ "Customer Auth" ] } }, "/v1/customer/auth/google/callback": { "get": { "operationId": "GoogleController_googleCallback", "summary": "Google OAuth callback for backend-mediated flow", "parameters": [ { "name": "code", "required": true, "in": "query", "description": "Authorization code from Google", "schema": { "type": "string" } }, { "name": "state", "required": true, "in": "query", "description": "Base64-encoded state payload", "schema": { "type": "string" } }, { "name": "error", "required": false, "in": "query", "description": "OAuth error code if authorization failed", "schema": { "type": "string" } }, { "name": "error_description", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirects to client with auth code" }, "400": { "description": "Missing code/state, invalid state, or OAuth error from Google" }, "401": { "description": "Failed to exchange code with Google" } }, "tags": [ "Customer Auth" ] } }, "/v1/customer/auth/google/sessions": { "post": { "operationId": "GoogleController_loginGoogle", "summary": "Exchange Google code for session", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleLoginZodDto" } } } }, "responses": { "200": { "description": "User session created" }, "401": { "description": "Failed to exchange code with Google" } }, "tags": [ "Customer Auth" ] } }, "/v1/customer/auth/github": { "get": { "operationId": "GitHubController_authorizeGithub", "summary": "Initiate GitHub OAuth flow for Customers", "parameters": [ { "name": "client_id", "required": true, "in": "query", "description": "OAuth client ID", "schema": { "type": "string" } }, { "name": "redirect_uri", "required": true, "in": "query", "description": "Redirect URI after authorization", "schema": { "type": "string" } }, { "name": "state", "required": false, "in": "query", "description": "Opaque state value forwarded to the callback", "schema": { "type": "string" } }, { "name": "scope", "required": false, "in": "query", "description": "Space-separated OAuth scopes", "schema": { "type": "string" } }, { "name": "code_challenge", "required": false, "in": "query", "description": "PKCE code challenge", "schema": { "type": "string" } }, { "name": "code_challenge_method", "required": false, "in": "query", "description": "PKCE method (S256)", "schema": { "type": "string" } }, { "name": "mcp_subdomain", "required": false, "in": "query", "description": "MCP server subdomain", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirects to GitHub consent screen" }, "400": { "description": "Missing client_id/redirect_uri or invalid client" } }, "tags": [ "Customer Auth" ] } }, "/v1/customer/auth/github/callback": { "get": { "operationId": "GitHubController_githubCallback", "summary": "GitHub OAuth callback for backend-mediated flow", "parameters": [ { "name": "code", "required": true, "in": "query", "description": "Authorization code from GitHub", "schema": { "type": "string" } }, { "name": "state", "required": true, "in": "query", "description": "Base64-encoded state payload", "schema": { "type": "string" } }, { "name": "error", "required": false, "in": "query", "description": "OAuth error code if authorization failed", "schema": { "type": "string" } }, { "name": "error_description", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirects to client with auth code" }, "400": { "description": "Missing code/state, invalid state, or OAuth error from GitHub" }, "401": { "description": "Failed to exchange code with GitHub" } }, "tags": [ "Customer Auth" ] } }, "/v1/customer/auth/github/sessions": { "post": { "operationId": "GitHubController_loginGithub", "summary": "Exchange GitHub code for session", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GithubLoginZodDto" } } } }, "responses": { "200": { "description": "User session created" }, "401": { "description": "Failed to exchange code with GitHub" } }, "tags": [ "Customer Auth" ] } }, "/v1/customer/auth/password-resets": { "post": { "operationId": "PasswordController_forgotPassword", "summary": "Request password reset", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordDto" } } } }, "responses": { "200": { "description": "Password reset email sent (if account exists)" }, "400": { "description": "Missing client_id or email" } }, "tags": [ "Customer Auth" ] } }, "/v1/customer/auth/password-resets/verifications": { "post": { "operationId": "PasswordController_resetPassword", "summary": "Reset password with token", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordDto" } } } }, "responses": { "200": { "description": "Password reset successfully" }, "400": { "description": "Missing required fields or invalid token" } }, "tags": [ "Customer Auth" ] } }, "/v1/operations/auth/google": { "get": { "operationId": "OperationsAuthController_googleAuth", "summary": "Operations Google OAuth initiation", "parameters": [ { "name": "returnTo", "required": false, "in": "query", "description": "Relative path to redirect after auth", "schema": {} } ], "responses": { "302": { "description": "Redirects to Google OAuth consent screen" } }, "tags": [ "Operations Auth" ] } }, "/v1/operations/auth/google/callback": { "get": { "operationId": "OperationsAuthController_googleCallback", "summary": "Operations Google OAuth callback", "parameters": [], "responses": { "302": { "description": "Redirect to frontend" } }, "tags": [ "Operations Auth" ] } }, "/v1/operations/auth/google/sessions": { "post": { "operationId": "OperationsAuthController_googleSession", "summary": "Create operations session from Google OAuth", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpsGoogleSessionDto" } } } }, "responses": { "200": { "description": "Session created (tokens issued), or MFA required (requiresMfa: true), or MFA setup required (requiresMfaSetup: true)" }, "401": { "description": "User not found or not a super admin" }, "403": { "description": "Email domain not allowed" } }, "tags": [ "Operations Auth" ] } }, "/v1/operations/auth/two-factor-verifications": { "post": { "operationId": "OperationsAuthController_verifyMfa", "summary": "Verify MFA for operations login", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpsMfaVerifyDto" } } } }, "responses": { "200": { "description": "MFA verified, tokens issued" }, "401": { "description": "Invalid MFA code or user not found" }, "403": { "description": "User is not a super admin" } }, "tags": [ "Operations Auth" ] } }, "/v1/ui/oauth/clients": { "post": { "operationId": "OAuthClientsController_createClient", "summary": "Create OAuth client", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOAuthClientDto" } } } }, "responses": { "201": { "description": "OAuth client created successfully" }, "400": { "description": "Validation failed" }, "404": { "description": "Provider not found" } }, "tags": [ "Provider OAuth Clients" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "OAuthClientsController_listClients", "summary": "List OAuth clients for provider", "parameters": [], "responses": { "200": { "description": "List of OAuth clients" } }, "tags": [ "Provider OAuth Clients" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/oauth/clients/{reference}": { "get": { "operationId": "OAuthClientsController_getClient", "summary": "Get OAuth client by reference", "parameters": [ { "name": "reference", "required": true, "in": "path", "description": "OAuth client reference ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OAuth client details" }, "404": { "description": "OAuth client not found" } }, "tags": [ "Provider OAuth Clients" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "OAuthClientsController_updateClient", "summary": "Update OAuth client", "parameters": [ { "name": "reference", "required": true, "in": "path", "description": "OAuth client reference ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOAuthClientDto" } } } }, "responses": { "200": { "description": "OAuth client updated successfully" }, "400": { "description": "Validation failed" }, "404": { "description": "OAuth client not found" } }, "tags": [ "Provider OAuth Clients" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "OAuthClientsController_deleteClient", "summary": "Delete OAuth client", "parameters": [ { "name": "reference", "required": true, "in": "path", "description": "OAuth client reference ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "OAuth client deleted successfully" }, "404": { "description": "OAuth client or provider not found" } }, "tags": [ "Provider OAuth Clients" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/oauth/clients/{reference}/reveal-secret": { "get": { "operationId": "OAuthClientsController_revealSecret", "summary": "Reveal OAuth client secret", "parameters": [ { "name": "reference", "required": true, "in": "path", "description": "OAuth client reference ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Client secret revealed" }, "404": { "description": "OAuth client or provider not found" } }, "tags": [ "Provider OAuth Clients" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/oauth/clients/{reference}/regenerate-secret": { "post": { "operationId": "OAuthClientsController_regenerateSecret", "summary": "Regenerate OAuth client secret", "parameters": [ { "name": "reference", "required": true, "in": "path", "description": "OAuth client reference ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "New client secret generated" }, "404": { "description": "OAuth client or provider not found" } }, "tags": [ "Provider OAuth Clients" ], "security": [ { "bearer": [] } ] } }, "/v1/provider-mcp/oauth/.well-known/oauth-authorization-server": { "get": { "operationId": "ProviderMcpOAuthController_authorizationServerMetadata", "summary": "OAuth 2.0 Authorization Server Metadata (RFC 8414) for Provider MCP", "parameters": [], "responses": { "200": { "description": "Server metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "registration_endpoint": { "type": "string" }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Provider MCP OAuth" ] } }, "/v1/provider-mcp/oauth/register": { "post": { "operationId": "ProviderMcpOAuthController_register", "summary": "Dynamic Client Registration for Provider MCP (dashboard OAuth)", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamicClientRegistrationDto" } } } }, "responses": { "201": { "description": "Client registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamicClientRegistrationResponseDto" } } } }, "400": { "description": "Invalid registration parameters" } }, "tags": [ "Provider MCP OAuth" ] } }, "/v1/provider-mcp/oauth/authorize": { "get": { "operationId": "ProviderMcpOAuthController_authorize", "summary": "Start Provider MCP OAuth authorization", "parameters": [ { "name": "client_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "redirect_uri", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "response_type", "required": true, "in": "query", "description": "Must be \"code\"", "schema": { "type": "string" } }, { "name": "code_challenge", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "code_challenge_method", "required": true, "in": "query", "description": "Must be \"S256\"", "schema": { "type": "string" } }, { "name": "state", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "scope", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirects to frontend IdP selection page" }, "400": { "description": "Missing or invalid OAuth parameters" } }, "tags": [ "Provider MCP OAuth" ] } }, "/v1/provider-mcp/oauth/attach": { "post": { "operationId": "ProviderMcpOAuthController_attach", "summary": "Bind authenticated provider user to Provider MCP OAuth session (after IdP login)", "parameters": [ { "name": "authorization", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionKey" ], "properties": { "sessionKey": { "type": "string" } } } } } }, "responses": { "200": { "description": "User attached", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Missing sessionKey" }, "401": { "description": "Bearer token required or invalid" } }, "tags": [ "Provider MCP OAuth" ], "security": [ { "bearer": [] } ] } }, "/v1/provider-mcp/oauth/consent": { "post": { "operationId": "ProviderMcpOAuthController_consent", "summary": "Approve or deny MCP client access", "parameters": [ { "name": "authorization", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionKey", "allow" ], "properties": { "sessionKey": { "type": "string" }, "allow": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Consent processed", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectUrl": { "type": "string" } } } } } }, "400": { "description": "Missing sessionKey or allow" }, "401": { "description": "Bearer token required or invalid" } }, "tags": [ "Provider MCP OAuth" ], "security": [ { "bearer": [] } ] } }, "/v1/provider-mcp/oauth/session": { "get": { "operationId": "ProviderMcpOAuthController_sessionInfo", "summary": "Hints for consent UI (client name, scopes)", "parameters": [ { "name": "sessionKey", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session info for consent UI" }, "400": { "description": "Missing sessionKey" }, "404": { "description": "Session not found or expired" } }, "tags": [ "Provider MCP OAuth" ] } }, "/v1/provider-mcp/oauth/token": { "post": { "operationId": "ProviderMcpOAuthController_token", "summary": "OAuth 2.0 token endpoint (access_token is the dashboard JWT)", "parameters": [ { "name": "authorization", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "grant_type", "code", "redirect_uri", "code_verifier" ], "properties": { "grant_type": { "type": "string", "example": "authorization_code" }, "code": { "type": "string" }, "redirect_uri": { "type": "string" }, "code_verifier": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" } } } } } }, "responses": { "200": { "description": "Token issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "number" } } } } } }, "400": { "description": "Invalid grant, code, or verifier" }, "401": { "description": "Invalid client credentials" } }, "tags": [ "Provider MCP OAuth" ] } }, "/v1/ui/provider/auth/cli-init/sessions": { "post": { "operationId": "CliInitController_createSession", "summary": "Create SolvaPay CLI init session", "parameters": [], "responses": { "201": { "description": "Init session created" } }, "tags": [ "CLI Init Auth" ] } }, "/v1/ui/provider/auth/cli-init/sessions/{sessionId}/completions": { "post": { "operationId": "CliInitController_completeSession", "summary": "Complete SolvaPay CLI init session after browser auth", "parameters": [], "responses": { "200": { "description": "Init session completed" } }, "tags": [ "CLI Init Auth" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/provider/auth/cli-init/sessions/{sessionId}/exchange": { "post": { "operationId": "CliInitController_exchangeSession", "summary": "Exchange completed init session for SolvaPay key", "parameters": [ { "name": "authorization", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Secret key exchange successful" } }, "tags": [ "CLI Init Auth" ] } }, "/v1/ui/provider/auth/cli-init/sessions/{sessionId}": { "get": { "operationId": "CliInitController_getSessionStatus", "summary": "Get init session status", "parameters": [], "responses": { "200": { "description": "Session status" } }, "tags": [ "CLI Init Auth" ] } }, "/v1/sdk/products/{productRef}/plans": { "get": { "operationId": "PlanSdkController_listPlans", "summary": "List plans for a product", "parameters": [ { "name": "productRef", "required": true, "in": "path", "description": "Product reference or ID", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Plans retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "total": { "type": "number", "description": "Total number of plans for the product" }, "limit": { "type": "number" }, "offset": { "type": "number" } } } } } }, "404": { "description": "Product not found" } }, "tags": [ "Plans" ], "security": [ { "SecretKey": [] } ] }, "post": { "operationId": "PlanSdkController_createPlan", "summary": "Create a plan for a product", "parameters": [ { "name": "productRef", "required": true, "in": "path", "description": "Product reference or ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlanRequest" } } } }, "responses": { "201": { "description": "Plan created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "404": { "description": "Product not found" } }, "tags": [ "Plans" ], "security": [ { "SecretKey": [] } ] } }, "/v1/sdk/products/{productRef}/plans/{planRef}": { "get": { "operationId": "PlanSdkController_getPlan", "summary": "Get a plan for a product", "parameters": [ { "name": "productRef", "required": true, "in": "path", "description": "Product reference or ID", "schema": { "type": "string" } }, { "name": "planRef", "required": true, "in": "path", "description": "Plan reference or ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plan retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "404": { "description": "Plan or product not found" } }, "tags": [ "Plans" ], "security": [ { "SecretKey": [] } ] }, "put": { "operationId": "PlanSdkController_updatePlan", "summary": "Update a plan for a product", "parameters": [ { "name": "productRef", "required": true, "in": "path", "description": "Product reference or ID", "schema": { "type": "string" } }, { "name": "planRef", "required": true, "in": "path", "description": "Plan reference or ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePlanRequest" } } } }, "responses": { "200": { "description": "Plan updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "404": { "description": "Plan or product not found" } }, "tags": [ "Plans" ], "security": [ { "SecretKey": [] } ] }, "delete": { "operationId": "PlanSdkController_deletePlan", "summary": "Delete a plan from a product", "parameters": [ { "name": "productRef", "required": true, "in": "path", "description": "Product reference or ID", "schema": { "type": "string" } }, { "name": "planRef", "required": true, "in": "path", "description": "Plan reference or ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plan deleted successfully" }, "404": { "description": "Plan or product not found" } }, "tags": [ "Plans" ], "security": [ { "SecretKey": [] } ] } }, "/v1/sdk/products": { "get": { "operationId": "ProductSdkController_listProducts", "summary": "List products", "description": "Retrieves a paginated list of products for the authenticated provider. Supports filtering by status, search term, and MCP Pay flag.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Max results (1-100)", "schema": { "example": 50, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Pagination offset", "schema": { "example": 0, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Search by name or description", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by status", "schema": { "enum": [ "active", "inactive", "suspended" ], "type": "string" } }, { "name": "isMcpPay", "required": false, "in": "query", "description": "Filter MCP Pay products", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Products retrieved successfully" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "ProductSdkController_createProduct", "summary": "Create a product", "description": "Creates a new product for the authenticated provider.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductRequest" } } } }, "responses": { "201": { "description": "Product created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkProductResponse" } } } }, "400": { "description": "Missing required fields or validation error" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/products/{productRef}": { "put": { "operationId": "ProductSdkController_updateProduct", "summary": "Update a product", "description": "Updates an existing product. Only provided fields are updated.", "parameters": [ { "name": "productRef", "required": true, "in": "path", "description": "Product reference or ID", "schema": { "example": "prd_1A2B3C4D", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductRequest" } } } }, "responses": { "200": { "description": "Product updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkProductResponse" } } } }, "404": { "description": "Product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "ProductSdkController_deleteProduct", "summary": "Delete a product", "description": "Deletes a product permanently in sandbox. In live mode, soft-deletes (preserves data but hides from listings). If the product has purchases in live mode, deactivates instead.", "parameters": [ { "name": "productRef", "required": true, "in": "path", "description": "Product reference or ID", "schema": { "example": "prd_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "description": "Product deleted or deactivated successfully" }, "404": { "description": "Product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "ProductSdkController_getProduct", "summary": "Get a product by reference", "description": "Retrieves a product by its reference or ID, including embedded plans.", "parameters": [ { "name": "productRef", "required": true, "in": "path", "description": "Product reference or ID", "schema": { "example": "prd_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "description": "Product retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkProductResponse" } } } }, "404": { "description": "Product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/products/mcp/bootstrap": { "post": { "operationId": "ProductSdkController_bootstrapMcpProduct", "summary": "Bootstrap MCP product integration", "description": "Creates an MCP-enabled product with a unified plans array, configures origin URL, and maps tools to plans in one request.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpBootstrapDto" } } } }, "responses": { "201": { "description": "MCP product bootstrapped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpBootstrapResult" } } } }, "400": { "description": "Invalid bootstrap request" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/products/{productRef}/mcp/plans": { "put": { "operationId": "ProductSdkController_configureMcpPlans", "summary": "Configure MCP plans on an MCP product", "description": "Configures plans and optional tool-to-plan mappings for an MCP product.", "parameters": [ { "name": "productRef", "required": true, "in": "path", "description": "Product reference or ID", "schema": { "example": "prd_1A2B3C4D", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureMcpPlansDto" } } } }, "responses": { "200": { "description": "MCP plans configured successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureMcpPlansResult" } } } }, "400": { "description": "Invalid MCP plans request or product is not MCP-enabled" }, "404": { "description": "Product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/products/{productRef}/clone": { "post": { "operationId": "ProductSdkController_cloneProduct", "summary": "Clone a product", "description": "Deep-copies a product including all its plans. Generates new references for the clone.", "parameters": [ { "name": "productRef", "required": true, "in": "path", "description": "Product reference or ID to clone", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneProductDto" } } } }, "responses": { "201": { "description": "Product cloned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkProductResponse" } } } }, "404": { "description": "Product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/products": { "get": { "operationId": "ProductUiController_listProducts", "summary": "List products for dashboard", "description": "Retrieves a paginated list of products with embedded plans.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Max results", "schema": { "example": 50, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Pagination offset", "schema": { "example": 0, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Search by name or description", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by status", "schema": { "type": "string" } }, { "name": "isMcpPay", "required": false, "in": "query", "description": "Filter MCP Pay products", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Products retrieved successfully" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "ProductUiController_createProduct", "summary": "Create a product", "description": "Creates a new product with optional image upload.", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateProductUiDto" } } } }, "responses": { "201": { "description": "Product created successfully" }, "400": { "description": "Missing required fields" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/products/name-checks": { "post": { "operationId": "ProductUiController_checkNameAvailability", "summary": "Check product name availability", "description": "Checks whether a product name is already taken for the current provider. Used for realtime validation during product creation.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckProductNameDto" } } } }, "responses": { "200": { "description": "Name availability result", "content": { "application/json": { "schema": { "type": "object", "properties": { "isUnique": { "type": "boolean" } } } } } } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/products/mcp/bootstrap/preview": { "post": { "operationId": "ProductUiController_previewBootstrap", "summary": "Preview MCP bootstrap", "description": "Validates MCP bootstrap payload and discovers tools from origin without creating resources.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpBootstrapDto" } } } }, "responses": { "200": { "description": "Bootstrap preview generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpBootstrapPreviewResult" } } } }, "400": { "description": "Invalid bootstrap preview payload" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/products/mcp/bootstrap": { "post": { "operationId": "ProductUiController_bootstrapMcpProduct", "summary": "Bootstrap MCP product integration for UI", "description": "Creates an MCP-enabled product with a unified plans array, configures origin URL, and maps tools to plans in one request.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpBootstrapDto" } } } }, "responses": { "201": { "description": "MCP product bootstrapped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpBootstrapResult" } } } }, "400": { "description": "Invalid bootstrap request" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/products/{id}/mcp/plans": { "put": { "operationId": "ProductUiController_configureMcpPlans", "summary": "Configure MCP plans on an MCP product", "description": "Configures plans and optional tool-to-plan mappings for an MCP product.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureMcpPlansDto" } } } }, "responses": { "200": { "description": "MCP plans configured successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureMcpPlansResult" } } } }, "400": { "description": "Invalid MCP plans request or product is not MCP-enabled" }, "404": { "description": "Product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/products/{id}": { "put": { "operationId": "ProductUiController_updateProduct", "summary": "Update a product", "description": "Updates an existing product with optional image upload.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UpdateProductUiDto" } } } }, "responses": { "200": { "description": "Product updated successfully" }, "404": { "description": "Product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "ProductUiController_deleteProduct", "summary": "Delete a product", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product deleted or deactivated successfully" }, "404": { "description": "Product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "ProductUiController_getProduct", "summary": "Get a product", "description": "Retrieves a product by ID or reference, including embedded plans.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product ID or reference", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product retrieved successfully" }, "404": { "description": "Product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/products/{id}/clone": { "post": { "operationId": "ProductUiController_cloneProduct", "summary": "Clone a product", "description": "Deep-copies a product including all its embedded plans with new references.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product ID or reference to clone", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneProductDto" } } } }, "responses": { "201": { "description": "Product cloned successfully" }, "404": { "description": "Product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/products/{id}/plans": { "get": { "operationId": "ProductUiController_getProductPlans", "summary": "List plans for a product", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product ID or reference", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plans retrieved successfully" }, "404": { "description": "Product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "ProductUiController_createPlan", "summary": "Create a plan within a product", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product ID or reference", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlanRequest" } } } }, "responses": { "201": { "description": "Plan created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "404": { "description": "Product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/products/{id}/plans/{planId}": { "put": { "operationId": "ProductUiController_updatePlan", "summary": "Update a plan within a product", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product ID or reference", "schema": { "type": "string" } }, { "name": "planId", "required": true, "in": "path", "description": "Plan ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePlanRequest" } } } }, "responses": { "200": { "description": "Plan updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "404": { "description": "Plan or product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "ProductUiController_deletePlan", "summary": "Delete a plan from a product", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product ID or reference", "schema": { "type": "string" } }, { "name": "planId", "required": true, "in": "path", "description": "Plan ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plan deleted successfully" }, "404": { "description": "Plan or product not found" } }, "tags": [ "Products" ], "security": [ { "bearer": [] } ] } }, "/v1/usage/analytics/product/{productId}/events": { "get": { "operationId": "UsageAnalyticsUiController_getProductUsageEvents", "summary": "List product usage events", "description": "Retrieves usage events for a product for the authenticated provider.", "parameters": [ { "name": "productId", "required": true, "in": "path", "description": "Product ID", "schema": { "type": "string" } }, { "name": "toolName", "required": false, "in": "query", "description": "Filter by tool name", "schema": { "type": "string" } }, { "name": "outcome", "required": false, "in": "query", "description": "Filter by outcome", "schema": { "enum": [ "success", "paywall", "fail" ], "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Start date (ISO 8601)", "schema": { "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date (ISO 8601)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Max results (default 100, max 1000)", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Offset for pagination (default 0)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List of product usage events matching the filters" } }, "tags": [ "Usage Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/usage/analytics/product/{productId}/stats": { "get": { "operationId": "UsageAnalyticsUiController_getProductUsageStats", "summary": "Get product usage stats", "description": "Returns dashboard-friendly usage stats for a product, including totals, daily time series, and breakdown by tool.", "parameters": [ { "name": "productId", "required": true, "in": "path", "description": "Product ID", "schema": { "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Start date (ISO 8601)", "schema": { "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date (ISO 8601)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dashboard-friendly product usage stats including totals, daily time series, and breakdown by tool" } }, "tags": [ "Usage Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/usage/analytics/purchase/{purchaseId}": { "get": { "operationId": "UsageAnalyticsUiController_getPurchaseUsageSummary", "summary": "Get usage summary for a purchase", "description": "Retrieves usage summary for a specific purchase/purchase.", "parameters": [ { "name": "purchaseId", "required": true, "in": "path", "description": "Purchase ID", "schema": { "type": "string" } }, { "name": "providerId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Start date (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date (ISO 8601 format)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage summary for the specified purchase" } }, "tags": [ "Usage Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/usage/analytics/customer/{customerId}": { "get": { "operationId": "UsageAnalyticsUiController_getCustomerUsageSummaries", "summary": "Get customer usage summaries", "description": "Retrieves usage summaries for all purchases/purchases of a customer.", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer ID", "schema": { "type": "string" } }, { "name": "providerId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Start date (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date (ISO 8601 format)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of usage summaries for all purchases of the customer" } }, "tags": [ "Usage Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/usage/analytics/product/{productId}/summaries": { "get": { "operationId": "UsageAnalyticsUiController_getProductUsageSummaries", "summary": "Get product usage summaries", "description": "Retrieves usage summaries for all purchases associated with a product.", "parameters": [ { "name": "productId", "required": true, "in": "path", "description": "Product ID", "schema": { "type": "string" } }, { "name": "providerId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Start date (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date (ISO 8601 format)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of usage summaries for all purchases associated with the product" } }, "tags": [ "Usage Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/usage/analytics/provider/{providerId}": { "get": { "operationId": "UsageAnalyticsUiController_getProviderUsageStatistics", "summary": "Get provider usage statistics", "description": "Retrieves overall usage statistics for all purchases/purchases of a provider.", "parameters": [ { "name": "providerId", "required": true, "in": "path", "description": "Provider ID", "schema": { "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Start date (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date (ISO 8601 format)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Overall usage statistics for all purchases of the provider" } }, "tags": [ "Usage Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/usages": { "post": { "operationId": "UsageSdkController_recordUsage", "summary": "Record a usage event", "description": "Records a usage event into the Usage timeseries collection.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUsageRequest" } } } }, "responses": { "200": { "description": "Usage recorded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "reference": { "type": "string", "example": "usage_A1B2C3D4" } } } } } }, "400": { "description": "Validation failed" } }, "tags": [ "Usage" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/usages/bulk": { "post": { "operationId": "UsageSdkController_recordBulkUsage", "summary": "Record bulk usage events", "description": "Records multiple usage events in a single request.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreateUsageRequest" } } } }, "responses": { "200": { "description": "Bulk usage events processed" }, "400": { "description": "Validation failed" } }, "tags": [ "Usage" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/meters": { "get": { "operationId": "MeterUiController_listMeters", "summary": "List all meters for the authenticated provider", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "active", "archived" ], "type": "string" } } ], "responses": { "200": { "description": "List of meters" } }, "tags": [ "Meters" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/meters/{reference}/usage": { "get": { "operationId": "MeterUiController_getMeterUsage", "summary": "Get aggregated usage for a meter", "parameters": [ { "name": "reference", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "from", "required": true, "in": "query", "description": "Start date (ISO 8601)", "schema": { "type": "string" } }, { "name": "to", "required": true, "in": "query", "description": "End date (ISO 8601)", "schema": { "type": "string" } }, { "name": "granularity", "required": false, "in": "query", "description": "Time bucket granularity (default: day)", "schema": { "enum": [ "hour", "day", "week", "month" ], "type": "string" } }, { "name": "customerId", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Aggregated usage data" } }, "tags": [ "Meters" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/meter-events": { "post": { "operationId": "MeterEventsSdkController_recordEvent", "summary": "Record a meter event", "description": "Records a single usage event against a named meter.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordMeterEventZodDto" } } } }, "responses": { "200": { "description": "Event recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Invalid meter name or meter is archived" } }, "tags": [ "Meter Events" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/meter-events/bulk": { "post": { "operationId": "MeterEventsSdkController_recordBulkEvents", "summary": "Record meter events in bulk", "description": "Records multiple usage events in a single request for high throughput.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordBulkMeterEventsZodDto" } } } }, "responses": { "200": { "description": "Events recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "inserted": { "type": "number", "example": 50 } } } } } }, "400": { "description": "Invalid meter name or meter is archived" } }, "tags": [ "Meter Events" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/transactions": { "get": { "operationId": "TransactionUiController_getTransactions", "summary": "Get transaction history for Provider", "parameters": [ { "name": "currency", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "transactionType", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "fromDate", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "toDate", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "offset", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "productId", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "entityId", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "customerId", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction history retrieved successfully" } }, "tags": [ "Transactions" ] } }, "/v1/ui/transactions/stats": { "get": { "operationId": "TransactionUiController_getTransactionStats", "summary": "Get transaction statistics for Provider", "parameters": [ { "name": "currency", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "fromDate", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "toDate", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction statistics retrieved successfully" } }, "tags": [ "Transactions" ] } }, "/v1/ui/transactions/refunds": { "post": { "operationId": "TransactionUiController_refundTransaction", "summary": "Refund a transaction", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundTransactionDto" } } } }, "responses": { "200": { "description": "Refund initiated successfully" } }, "tags": [ "Transactions" ] } }, "/v1/ui/transactions/cancellations": { "post": { "operationId": "TransactionUiController_cancelTransaction", "summary": "Cancel a transaction", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelTransactionDto" } } } }, "responses": { "200": { "description": "Transaction cancelled successfully" } }, "tags": [ "Transactions" ] } }, "/v1/ui/transactions/{transactionId}": { "get": { "operationId": "TransactionUiController_getTransactionById", "summary": "Get specific transaction by ID", "parameters": [ { "name": "transactionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction retrieved successfully" } }, "tags": [ "Transactions" ] } }, "/v1/ui/transactions/{transactionId}/events": { "get": { "operationId": "TransactionUiController_getTransactionEvents", "summary": "Get all events for a specific transaction", "parameters": [ { "name": "transactionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction events retrieved successfully" } }, "tags": [ "Transactions" ] } }, "/v1/ui/admin/transactions": { "get": { "operationId": "AdminTransactionUiController_getAllTransactions", "summary": "Get all transactions (admin only)", "parameters": [ { "name": "currency", "required": false, "in": "query", "description": "Filter by currency", "schema": { "type": "string" } }, { "name": "transactionType", "required": false, "in": "query", "description": "Filter by transaction type", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by status", "schema": { "type": "string" } }, { "name": "fromDate", "required": false, "in": "query", "description": "Start date (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "toDate", "required": false, "in": "query", "description": "End date (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of transactions to return", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of transactions to skip", "schema": { "type": "number" } }, { "name": "providerId", "required": false, "in": "query", "description": "Filter by provider ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "All transactions retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } } }, "tags": [ "Admin Transactions" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/transactions/stats": { "get": { "operationId": "AdminTransactionUiController_getSystemTransactionStats", "summary": "Get system-wide transaction statistics (admin only)", "parameters": [ { "name": "currency", "required": false, "in": "query", "description": "Filter by currency", "schema": { "type": "string" } }, { "name": "fromDate", "required": false, "in": "query", "description": "Start date (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "toDate", "required": false, "in": "query", "description": "End date (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "providerId", "required": false, "in": "query", "description": "Filter by provider ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } } }, "tags": [ "Admin Transactions" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/transactions/by-id/{transactionId}": { "get": { "operationId": "AdminTransactionUiController_getTransactionById", "summary": "Get specific transaction by ID (admin only)", "parameters": [ { "name": "transactionId", "required": true, "in": "path", "description": "Transaction ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Transaction not found" } }, "tags": [ "Admin Transactions" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/transactions/balance": { "get": { "operationId": "AdminTransactionUiController_getProviderBalance", "summary": "Get balance for specific provider (admin only)", "parameters": [ { "name": "providerId", "required": true, "in": "query", "description": "Provider ID", "schema": { "type": "string" } }, { "name": "currency", "required": false, "in": "query", "description": "Currency code", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Balance retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Provider ID is required" } }, "tags": [ "Admin Transactions" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/transactions/balance/history": { "get": { "operationId": "AdminTransactionUiController_getProviderBalanceHistory", "summary": "Get balance history for specific provider (admin only)", "parameters": [ { "name": "providerId", "required": true, "in": "query", "description": "Provider ID", "schema": { "type": "string" } }, { "name": "currency", "required": false, "in": "query", "description": "Currency code", "schema": { "type": "string" } }, { "name": "fromDate", "required": false, "in": "query", "description": "Start date (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "toDate", "required": false, "in": "query", "description": "End date (ISO 8601 format)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Balance history retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Provider ID is required" } }, "tags": [ "Admin Transactions" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/admin/transactions/system-balance": { "get": { "operationId": "AdminTransactionUiController_getSystemBalance", "summary": "Get system-wide balance summary (admin only)", "parameters": [ { "name": "currency", "required": false, "in": "query", "description": "Currency code", "schema": { "type": "string" } } ], "responses": { "200": { "description": "System balance retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } } }, "tags": [ "Admin Transactions" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/mcp-servers": { "get": { "operationId": "McpUiController_listMcpServers", "summary": "List MCP servers", "description": "Retrieves all MCP servers for the authenticated provider.", "parameters": [], "responses": { "200": { "description": "List of MCP servers retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/McpServerDto" } } } } } }, "tags": [ "MCP Servers" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "McpUiController_createMcpServer", "summary": "Create a new MCP server", "description": "Creates a new MCP server. The server will be associated with the authenticated provider.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMcpServerDto" } } } }, "responses": { "201": { "description": "MCP server created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerDto" } } } } }, "tags": [ "MCP Servers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/mcp-servers/{id}": { "get": { "operationId": "McpUiController_getMcpServer", "summary": "Get MCP server by ID", "description": "Retrieves a specific MCP server by its ID.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "MCP server ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "MCP server retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerDto" } } } } }, "tags": [ "MCP Servers" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "McpUiController_updateMcpServer", "summary": "Update MCP server", "description": "Updates an existing MCP server.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "MCP server ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMcpServerDto" } } } }, "responses": { "200": { "description": "MCP server updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerDto" } } } } }, "tags": [ "MCP Servers" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "McpUiController_deleteMcpServer", "summary": "Delete MCP server", "description": "Permanently deletes an MCP server.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "MCP server ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "MCP server deleted successfully" } }, "tags": [ "MCP Servers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/mcp-servers/name-checks": { "post": { "operationId": "McpUiController_checkNameUniqueness", "summary": "Check MCP domain availability", "description": "Checks if a normalized MCP domain slug is globally available. Used for realtime validation during MCP config updates.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckMcpNameDto" } } } }, "responses": { "200": { "description": "Name uniqueness check result", "content": { "application/json": { "schema": { "type": "object", "properties": { "isUnique": { "type": "boolean" }, "normalizedDomain": { "type": "string" } } } } } } }, "tags": [ "MCP Servers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/mcp-servers/bootstrap-subdomain-checks": { "post": { "operationId": "McpUiController_checkBootstrapSubdomain", "summary": "Resolve bootstrap subdomain and availability", "description": "Builds the effective bootstrap subdomain from provider identity + input slug and checks global availability.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckBootstrapSubdomainDto" } } } }, "responses": { "200": { "description": "Bootstrap subdomain resolution result", "content": { "application/json": { "schema": { "type": "object", "properties": { "effectiveSubdomain": { "type": "string" }, "isUnique": { "type": "boolean" } } } } } } }, "tags": [ "MCP Servers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/mcp-servers/discover-tools": { "post": { "operationId": "McpUiController_discoverTools", "summary": "Discover tools from MCP server", "description": "Discovers available tools from an MCP server URL.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverToolsDto" } } } }, "responses": { "200": { "description": "Tools discovered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } } } } } }, "tags": [ "MCP Servers" ], "security": [ { "bearer": [] } ] } }, "/v1/mcp/oauth-authorization-servers": { "get": { "operationId": "McpOAuthController_getAuthorizationServerMetadata", "summary": "OAuth Authorization Server Metadata", "description": "Returns OAuth 2.0 Authorization Server Metadata for MCP client discovery (RFC8414)", "parameters": [], "responses": { "200": { "description": "OAuth authorization server metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string", "example": "https://mytelescope.mcp.solvapay.com" }, "authorization_endpoint": { "type": "string", "example": "https://mytelescope.mcp.solvapay.com/v1/customer/auth/authorize" }, "token_endpoint": { "type": "string", "example": "https://mytelescope.mcp.solvapay.com/v1/customer/auth/token" }, "registration_endpoint": { "type": "string", "example": "https://mytelescope.mcp.solvapay.com/v1/customer/auth/register" }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" }, "example": [ "client_secret_basic", "client_secret_post" ] }, "response_types_supported": { "type": "array", "items": { "type": "string" }, "example": [ "code" ] }, "scopes_supported": { "type": "array", "items": { "type": "string" }, "example": [ "openid", "profile", "email" ] }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" }, "example": [ "S256" ] } } } } } } }, "tags": [ "MCP Discovery" ] } }, "/v1/mcp/openid-configuration": { "get": { "operationId": "McpOAuthController_getOpenIdConfiguration", "summary": "OpenID Connect Discovery", "description": "Returns OpenID Connect Discovery 1.0 configuration for client discovery", "parameters": [], "responses": { "200": { "description": "OpenID Connect configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "userinfo_endpoint": { "type": "string" }, "registration_endpoint": { "type": "string" }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "subject_types_supported": { "type": "array", "items": { "type": "string" } }, "id_token_signing_alg_values_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "claims_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "MCP Discovery" ] } }, "/v1/mcp/non-hosted-discovery": { "get": { "operationId": "McpOAuthController_getNonHostedDiscoveryMetadata", "summary": "Non-hosted MCP discovery helper", "description": "Returns protected resource and authorization server metadata for non-hosted MCP servers", "parameters": [ { "name": "resource", "required": true, "in": "query", "description": "Absolute URL of the resource server", "schema": { "type": "string" } }, { "name": "product_ref", "required": true, "in": "query", "description": "Product reference for registration binding", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Discovery metadata for the non-hosted resource" }, "400": { "description": "Missing or invalid resource/product_ref" } }, "tags": [ "MCP Discovery" ] } }, "/v1/mcp/oauth-protected-resource": { "get": { "operationId": "McpOAuthController_getProtectedResourceMetadata", "summary": "OAuth Protected Resource Metadata", "description": "Returns OAuth 2.0 Protected Resource Metadata for MCP client discovery (RFC9728)", "parameters": [], "responses": { "200": { "description": "OAuth protected resource metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource": { "type": "string", "example": "https://mytelescope.mcp.solvapay.com" }, "authorization_servers": { "type": "array", "items": { "type": "string" }, "example": [ "https://mytelescope.mcp.solvapay.com" ] }, "scopes_supported": { "type": "array", "items": { "type": "string" }, "example": [ "openid", "profile", "email" ] } } } } } } }, "tags": [ "MCP Discovery" ] } }, "/v1/mcps/routings": { "get": { "operationId": "McpRoutingController_routeMcpRequest", "summary": "MCP request routing", "description": "Internal auth-subrequest endpoint used by nginx. Validates the MCP subdomain, JWT bearer token, and tool-level purchase access before allowing the request to be proxied to the origin MCP server.", "parameters": [ { "name": "x-original-host", "required": true, "in": "header", "description": "Original Host header forwarded by nginx", "schema": { "type": "string" } }, { "name": "x-original-uri", "required": false, "in": "header", "description": "Original URI forwarded by nginx", "schema": { "type": "string" } }, { "name": "authorization", "required": false, "in": "header", "description": "Bearer token with customerRef and providerId claims", "schema": { "type": "string" } }, { "name": "mcp_method", "required": false, "in": "query", "description": "MCP JSON-RPC method (e.g. initialize, tools/list, tools/call)", "schema": { "type": "string" } }, { "name": "mcp_tool_name", "required": false, "in": "query", "description": "Tool name for tools/call requests", "schema": { "type": "string" } }, { "name": "mcp_id", "required": false, "in": "query", "description": "JSON-RPC request ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request authorized \u2014 nginx proxies to origin" }, "201": { "description": "Intercepted response returned directly (e.g. tools/list with virtual tools)" }, "401": { "description": "Missing or invalid bearer token" }, "402": { "description": "Payment required \u2014 tool access denied" }, "404": { "description": "MCP server not found for subdomain" } }, "tags": [ "MCP - Routing" ] } }, "/v1/ui/purchases": { "get": { "operationId": "PurchaseUiController_getPurchases", "summary": "Get all purchases for provider", "parameters": [ { "name": "status", "required": false, "in": "query", "description": "Filter by status", "schema": { "enum": [ "pending", "active", "trialing", "past_due", "cancelled", "expired", "suspended", "refunded" ], "type": "string" } }, { "name": "productId", "required": false, "in": "query", "description": "Filter by product ID", "schema": { "type": "string" } }, { "name": "customerId", "required": false, "in": "query", "description": "Filter by customer ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Purchases retrieved successfully", "content": { "application/json": { "schema": { "properties": { "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseResponse" } } } } } } } }, "tags": [ "UI - Purchases" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/purchases/{id}": { "get": { "operationId": "PurchaseUiController_getPurchase", "summary": "Get a single purchase by ID or reference", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Purchase ID or reference", "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "description": "Purchase retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseResponse" } } } }, "404": { "description": "Purchase not found" } }, "tags": [ "UI - Purchases" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/purchases/{purchaseRef}/cancel": { "post": { "operationId": "PurchaseUiController_cancelPurchase", "summary": "Cancel a purchase", "parameters": [ { "name": "purchaseRef", "required": true, "in": "path", "description": "Purchase reference or ID", "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPurchaseRequest" } } } }, "responses": { "200": { "description": "Purchase cancelled successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "purchase": { "$ref": "#/components/schemas/PurchaseResponse" } } } } } }, "404": { "description": "Purchase not found" } }, "tags": [ "UI - Purchases" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/purchases/{purchaseRef}/reactivate": { "post": { "operationId": "PurchaseUiController_reactivatePurchase", "summary": "Reactivate a cancelled purchase", "parameters": [ { "name": "purchaseRef", "required": true, "in": "path", "description": "Purchase reference or ID", "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "description": "Purchase reactivated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "purchase": { "$ref": "#/components/schemas/PurchaseResponse" } } } } } }, "400": { "description": "Purchase cannot be reactivated" }, "404": { "description": "Purchase not found" } }, "tags": [ "UI - Purchases" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/purchases": { "get": { "operationId": "PurchaseSdkController_listPurchases", "summary": "List purchases for provider", "description": "Retrieves all purchases for the authenticated provider with optional filtering by status, product, or customer.", "parameters": [ { "name": "status", "required": false, "in": "query", "description": "Filter by purchase status", "schema": { "enum": [ "pending", "active", "trialing", "past_due", "cancelled", "expired", "suspended", "refunded" ], "type": "string" } }, { "name": "productRef", "required": false, "in": "query", "description": "Filter by product reference", "schema": { "type": "string" } }, { "name": "customerRef", "required": false, "in": "query", "description": "Filter by customer reference", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Purchases retrieved successfully", "content": { "application/json": { "schema": { "properties": { "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/SdkPurchaseResponse" } } } } } } } }, "tags": [ "Purchases" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/purchases/customer/{customerRef}": { "get": { "operationId": "PurchaseSdkController_getPurchasesForCustomer", "summary": "Get purchases for a customer", "description": "Retrieves all purchases for a specific customer. Useful for billing history and access checks.", "parameters": [ { "name": "customerRef", "required": true, "in": "path", "description": "Customer reference or ID", "schema": { "example": "cus_3C4D5E6F", "type": "string" } } ], "responses": { "200": { "description": "Customer purchases retrieved successfully", "content": { "application/json": { "schema": { "properties": { "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/SdkPurchaseResponse" } } } } } } }, "404": { "description": "Customer not found" } }, "tags": [ "Purchases" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/purchases/product/{productRef}": { "get": { "operationId": "PurchaseSdkController_getPurchasesForProduct", "summary": "Get purchases for a product", "description": "Retrieves all purchases for a specific product. Each billing period creates a new purchase document.", "parameters": [ { "name": "productRef", "required": true, "in": "path", "description": "Product reference or ID", "schema": { "example": "prd_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "description": "Product purchases retrieved successfully", "content": { "application/json": { "schema": { "properties": { "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/SdkPurchaseResponse" } } } } } } }, "404": { "description": "Product not found" } }, "tags": [ "Purchases" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/purchases/{purchaseRef}": { "get": { "operationId": "PurchaseSdkController_getPurchase", "summary": "Get a purchase by reference", "description": "Retrieves a single purchase including plan snapshot, usage, and billing details.", "parameters": [ { "name": "purchaseRef", "required": true, "in": "path", "description": "Purchase reference or ID", "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "description": "Purchase retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkPurchaseResponse" } } } }, "404": { "description": "Purchase not found" } }, "tags": [ "Purchases" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/purchases/{purchaseRef}/cancel": { "post": { "operationId": "PurchaseSdkController_cancelPurchase", "summary": "Cancel a purchase", "description": "Cancels an active purchase. For recurring purchases, cancellation takes effect at the end of the current billing period.", "parameters": [ { "name": "purchaseRef", "required": true, "in": "path", "description": "Purchase reference or ID", "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPurchaseRequest" } } } }, "responses": { "200": { "description": "Purchase cancelled successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "purchase": { "$ref": "#/components/schemas/SdkPurchaseResponse" } } } } } }, "404": { "description": "Purchase not found" } }, "tags": [ "Purchases" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/purchases/{purchaseRef}/reactivate": { "post": { "operationId": "PurchaseSdkController_reactivatePurchase", "summary": "Reactivate a cancelled purchase", "description": "Reactivates a purchase that was cancelled but has not yet reached its end date. Restores auto-renewal and clears cancellation fields.", "parameters": [ { "name": "purchaseRef", "required": true, "in": "path", "description": "Purchase reference or ID", "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "description": "Purchase reactivated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "purchase": { "$ref": "#/components/schemas/SdkPurchaseResponse" } } } } } }, "400": { "description": "Purchase cannot be reactivated" }, "404": { "description": "Purchase not found" } }, "tags": [ "Purchases" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/limits": { "post": { "operationId": "LimitsSdkController_checkLimits", "summary": "Check usage limits for a customer and product", "description": "Checks whether a customer has an active purchase for a product and is within their usage limits. Returns a checkout URL if payment is required.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckLimitRequest" } } } }, "responses": { "200": { "description": "Limit check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitResponse" } } } }, "400": { "description": "Missing customerRef or productRef" }, "404": { "description": "Customer or product not found" } }, "tags": [ "Limits" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/activate": { "post": { "operationId": "ActivateSdkController_activate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivatePlanDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivatePlanResponseDto" } } } } }, "tags": [ "Activation" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/customers": { "get": { "operationId": "CustomerUiController_getCustomers", "summary": "List customers", "description": "Retrieves a list of customers for the authenticated provider with optional search filtering.", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Search term to filter customers", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by derived customer status (active = has active purchases)", "schema": { "enum": [ "active", "inactive" ], "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of customers to return (default: 100)", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of customers to skip for pagination (default: 0)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Array of customer objects with enriched status and purchase data" } }, "tags": [ "Customers" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "CustomerUiController_createCustomer", "summary": "Create a new customer", "description": "Creates a new customer for the authenticated provider. The customer will be associated with the provider's organization.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" } } } }, "responses": { "201": { "description": "Customer created successfully" } }, "tags": [ "Customers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/customers/stats": { "get": { "operationId": "CustomerUiController_getCustomerStats", "summary": "Get customer statistics", "description": "Retrieves aggregated statistics for customers including total count, active customers, and revenue metrics.", "parameters": [], "responses": { "200": { "description": "Customer statistics including totalCustomers, activeCustomers, inactiveCustomers, newCustomersThisPeriod, and growthRate" } }, "tags": [ "Customers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/customers/{id}": { "get": { "operationId": "CustomerUiController_getCustomer", "summary": "Get customer by ID", "description": "Retrieves a specific customer by their ID. Only returns customers belonging to the authenticated provider.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Customer ID", "schema": { "example": "507f1f77bcf86cd799439011", "type": "string" } } ], "responses": { "200": { "description": "Customer retrieved successfully" }, "404": { "description": "Customer not found" } }, "tags": [ "Customers" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "CustomerUiController_updateCustomer", "summary": "Update customer", "description": "Updates an existing customer's information. Only customers belonging to the authenticated provider can be updated.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Customer ID", "schema": { "example": "507f1f77bcf86cd799439011", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerUiDto" } } } }, "responses": { "200": { "description": "Customer updated successfully" }, "404": { "description": "Customer not found" } }, "tags": [ "Customers" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "CustomerUiController_deleteCustomer", "summary": "Delete customer", "description": "Soft-deletes a customer. The customer data is preserved but hidden from active listings. Only customers belonging to the authenticated provider can be deleted.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Customer ID", "schema": { "example": "507f1f77bcf86cd799439011", "type": "string" } } ], "responses": { "204": { "description": "Customer soft-deleted successfully" }, "404": { "description": "Customer not found" } }, "tags": [ "Customers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/customers/payment-links/{reference}": { "get": { "operationId": "CustomerUiController_getPaymentLinkByReference", "summary": "Get payment link details by reference (public endpoint)", "description": "Retrieves payment link details by reference. This is a public endpoint and does not require authentication.", "parameters": [ { "name": "reference", "required": true, "in": "path", "description": "Payment link reference or session ID", "schema": { "example": "pyl_a1b2c3d4e5f6", "type": "string" } } ], "responses": { "200": { "description": "Payment link details retrieved successfully" }, "400": { "description": "Payment link expired or already used" }, "404": { "description": "Payment link not found" } }, "tags": [ "Customers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/customers/payment-links/process": { "post": { "operationId": "CustomerUiController_createPaymentFromLink", "summary": "Process payment for a payment link (public endpoint)", "description": "Processes a payment using a payment link and payment method. This is a public endpoint.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentFromLinkDto" } } } }, "responses": { "200": { "description": "Payment processed successfully" }, "400": { "description": "Payment processing failed" }, "404": { "description": "Payment link not found" } }, "tags": [ "Customers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/customers/customer-sessions/{sessionId}": { "get": { "operationId": "CustomerSessionUiController_getCustomerSession", "summary": "Get a customer session by sessionId", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Customer session ID", "schema": { "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" } } ], "responses": { "200": { "description": "Customer session retrieved successfully" }, "404": { "description": "Customer session not found or expired" } }, "tags": [ "Customers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/customers/customer-sessions": { "post": { "operationId": "CustomerSessionUiController_createCustomerSession", "summary": "Create a customer session for a customer", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerSessionRequest" }, "examples": { "allProducts": { "summary": "Create customer page session with all products", "value": { "customerRef": "cus_3c4d5e6f7g8h" } }, "scopedProduct": { "summary": "Create customer page session scoped to one product", "value": { "customerRef": "cus_3c4d5e6f7g8h", "productRef": "prd_a1b2c3d4e5f6" } } } } } }, "responses": { "201": { "description": "Customer session created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSessionResponse" } } } }, "400": { "description": "Invalid request parameters" }, "404": { "description": "Customer not found" } }, "tags": [ "Customers" ], "security": [ { "bearer": [] } ] } }, "/v1/sdk/customers": { "post": { "operationId": "CustomerSdkController_createCustomer", "summary": "Create a new customer", "description": "Creates a new customer record for the authenticated provider. Customers represent end-users who will purchase your products. Email is required and must be unique per provider. The name field is optional but recommended for better tracking.", "parameters": [], "requestBody": { "required": true, "description": "Customer creation data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" }, "examples": { "withName": { "summary": "Customer with name", "value": { "email": "customer@example.com", "name": "John Doe" } }, "emailOnly": { "summary": "Email only", "value": { "email": "customer@example.com" } } } } } }, "responses": { "201": { "description": "Customer created successfully", "schema": { "example": { "reference": "cus_3c4d5e6f7g8h", "name": "John Doe", "email": "customer@example.com", "externalRef": "auth_user_12345" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Invalid email or missing required fields", "content": { "application/json": { "schema": { "example": { "statusCode": 400, "message": "Invalid email format", "error": "Bad Request" } } } } } }, "tags": [ "Customers" ], "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "CustomerSdkController_getCustomerByQuery", "summary": "Get customer by reference, externalRef, or email", "description": "Retrieves a customer's details using their unique reference ID, externalRef, or email. Use query parameter 'reference' to look up by customer reference, 'externalRef' for external auth ID, or 'email' for customer email. Exactly one parameter must be provided. Returns the customer's name, email, and active purchases. Only customers owned by the authenticated provider can be accessed.", "parameters": [ { "name": "reference", "required": false, "in": "query", "description": "Customer reference identifier (use exactly one query parameter)", "schema": { "example": "cus_3c4d5e6f7g8h", "type": "string" } }, { "name": "externalRef", "required": false, "in": "query", "description": "External reference ID from your auth system (use exactly one query parameter)", "schema": { "example": "auth_user_12345", "type": "string" } }, { "name": "email", "required": false, "in": "query", "description": "Customer email address (use exactly one query parameter)", "schema": { "example": "customer@example.com", "type": "string" } } ], "responses": { "200": { "description": "Customer retrieved successfully", "schema": { "example": { "reference": "cus_3c4d5e6f7g8h", "name": "John Doe", "email": "customer@example.com", "externalRef": "auth_user_12345", "purchases": [ { "reference": "pur_1A2B3C4D", "productName": "API Gateway Manager", "productRef": "prd_abc123", "status": "active", "startDate": "2025-10-27T10:00:00Z", "amount": 9900, "currency": "USD", "endDate": "2025-11-27T10:00:00Z" } ] } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Invalid request - must provide exactly one of reference, externalRef, or email", "content": { "application/json": { "schema": { "example": { "statusCode": 400, "message": "Must provide exactly one of reference, externalRef, or email", "error": "Bad Request" } } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "example": { "statusCode": 404, "message": "Customer not found", "error": "Not Found" } } } } } }, "tags": [ "Customers" ], "security": [ { "SecretKey": [] } ] } }, "/v1/sdk/customers/{reference}/balance": { "get": { "operationId": "CustomerSdkController_getCustomerBalance", "summary": "Get customer credit balance", "description": "Returns the credit balance for a customer identified by reference.", "parameters": [ { "name": "reference", "required": true, "in": "path", "description": "Customer reference identifier", "schema": { "example": "cus_3c4d5e6f7g8h", "type": "string" } } ], "responses": { "200": { "description": "Customer balance retrieved successfully", "content": { "application/json": { "schema": { "example": { "customerRef": "cus_3c4d5e6f7g8h", "credits": 4200 } } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "example": { "statusCode": 404, "message": "Customer with reference cus_3c4d5e6f7g8h not found", "error": "Not Found" } } } } } }, "tags": [ "Customers" ], "security": [ { "SecretKey": [] } ] } }, "/v1/sdk/customers/{reference}": { "get": { "operationId": "CustomerSdkController_getCustomer", "summary": "Get customer by reference", "description": "Retrieves a customer's details using their unique reference ID. Returns the customer's name, email, and active purchases. Only customers owned by the authenticated provider can be accessed.", "parameters": [ { "name": "reference", "required": true, "in": "path", "description": "Customer reference identifier", "schema": { "example": "cus_3c4d5e6f7g8h", "type": "string" } } ], "responses": { "200": { "description": "Customer retrieved successfully", "schema": { "example": { "reference": "cus_3c4d5e6f7g8h", "name": "John Doe", "email": "customer@example.com", "externalRef": "auth_user_12345", "purchases": [ { "reference": "pur_1A2B3C4D", "productName": "API Gateway Manager", "productRef": "prd_abc123", "status": "active", "startDate": "2025-10-27T10:00:00Z", "amount": 9900, "currency": "USD", "endDate": "2025-11-27T10:00:00Z" } ] } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "example": { "statusCode": 404, "message": "Customer with reference cus_3c4d5e6f7g8h not found", "error": "Not Found" } } } } } }, "tags": [ "Customers" ], "security": [ { "SecretKey": [] } ] } }, "/v1/sdk/customers/customer-sessions": { "post": { "operationId": "CustomerSdkController_createCustomerSession", "summary": "Create a customer session", "description": "Creates a customer session URL that can be used to redirect customers to the customer page. Returns the customer URL and session ID. The session is short-lived (15 minutes) for security reasons.", "parameters": [], "requestBody": { "required": true, "description": "Customer session creation request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerSessionRequest" }, "examples": { "basic": { "summary": "Create customer session", "value": { "customerRef": "cus_3c4d5e6f7g8h" } } } } } }, "responses": { "201": { "description": "Customer session created successfully", "schema": { "example": { "sessionId": "e3f1c2d4b6a89f001122334455667788", "customerUrl": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerSessionResponse" } } } }, "400": { "description": "Invalid request data or customer not found", "content": { "application/json": { "schema": { "example": { "statusCode": 400, "message": "Customer not found", "error": "Bad Request" } } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "example": { "statusCode": 404, "message": "Customer not found", "error": "Not Found" } } } } } }, "tags": [ "Customers" ], "security": [ { "SecretKey": [] } ] } }, "/v1/sdk/customers/customer-sessions/{sessionId}": { "get": { "operationId": "CustomerSdkController_getCustomerSession", "summary": "Get customer session by sessionId", "description": "Retrieves a customer session by its sessionId with all data hydrated including customer details and purchases. The session must belong to the authenticated provider.", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Customer session ID/token", "schema": { "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" } } ], "responses": { "200": { "description": "Customer session retrieved successfully", "schema": { "example": { "sessionId": "e3f1c2d4b6a89f001122334455667788", "status": "active", "customerUrl": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788", "expiresAt": "2025-01-01T12:00:00.000Z", "customer": { "reference": "cus_3c4d5e6f7g8h", "name": "John Doe", "email": "customer@example.com", "externalRef": "auth_user_12345", "purchases": [ { "reference": "pur_1A2B3C4D", "productName": "API Gateway Manager", "productRef": "prd_abc123", "status": "active", "startDate": "2025-10-27T10:00:00Z", "amount": 9900, "currency": "USD", "endDate": "2025-11-27T10:00:00Z" } ] }, "createdAt": "2025-01-01T11:45:00.000Z", "updatedAt": "2025-01-01T11:45:00.000Z" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCustomerSessionResponse" } } } }, "404": { "description": "Customer session not found", "content": { "application/json": { "schema": { "example": { "statusCode": 404, "message": "Customer session not found: e3f1c2d4b6a89f001122334455667788", "error": "Not Found" } } } } } }, "tags": [ "Customers" ], "security": [ { "SecretKey": [] } ] } }, "/v1/sdk/user-info": { "post": { "operationId": "UserInfoSdkController_getUserInfo", "summary": "Get user info and purchase status", "description": "Returns customer profile, active purchase details including usage and plan info, and a customer portal URL.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfoRequest" } } } }, "responses": { "200": { "description": "User info with purchase status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfoResponse" } } } }, "400": { "description": "Missing customerRef or productRef" }, "404": { "description": "Customer or product not found" } }, "tags": [ "User Info" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/customers/me": { "get": { "operationId": "CustomerMeController_getMe", "summary": "Get current customer profile", "parameters": [], "responses": { "200": { "description": "Customer profile retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "example": "customer" }, "emailVerified": { "type": "boolean" }, "authProvider": { "type": "string", "example": "google" }, "providerId": { "type": "string" }, "preferences": { "type": "object" }, "roles": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Unauthorized" } }, "tags": [ "Customers" ], "security": [ { "bearer": [] } ] } }, "/v1/analytics/queries": { "post": { "operationId": "AdminAnalyticsUiController_getAvailableQueries", "summary": "Get list of available analytics queries", "parameters": [], "responses": { "200": { "description": "List of available analytics queries with their schemas" } }, "tags": [ "Admin Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/analytics/queries/schema": { "post": { "operationId": "AdminAnalyticsUiController_getQuerySchema", "summary": "Get parameter schema for a specific query", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuerySchemaRequestDto" } } } }, "responses": { "200": { "description": "Parameter schema for the specified query" } }, "tags": [ "Admin Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/analytics/executions": { "post": { "operationId": "AdminAnalyticsUiController_executeQuery", "summary": "Execute a single analytics query", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteAnalyticsQueryDto" } } } }, "responses": { "200": { "description": "Analytics query execution result" } }, "tags": [ "Admin Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/analytics/execute-multiple": { "post": { "operationId": "AdminAnalyticsUiController_executeMultipleQueries", "summary": "Execute multiple analytics queries in parallel", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteMultipleQueriesDto" } } } }, "responses": { "200": { "description": "Results from multiple analytics queries" } }, "tags": [ "Admin Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/analytics/system-overview": { "post": { "operationId": "AdminAnalyticsUiController_getSystemOverview", "summary": "Get system overview analytics data", "parameters": [], "responses": { "200": { "description": "System overview analytics data" } }, "tags": [ "Admin Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/analytics/validate": { "post": { "operationId": "AdminAnalyticsUiController_validateParameters", "summary": "Validate parameters for a specific query", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateParametersDto" } } } }, "responses": { "200": { "description": "Parameter validation result" } }, "tags": [ "Admin Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/provider/analytics/queries": { "post": { "operationId": "ProviderAnalyticsUiController_getAvailableQueries", "summary": "Get list of available provider analytics queries", "parameters": [], "responses": { "200": { "description": "List of available provider analytics queries with their schemas" } }, "tags": [ "Provider Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/provider/analytics/queries/schema": { "post": { "operationId": "ProviderAnalyticsUiController_getQuerySchema", "summary": "Get parameter schema for a specific provider query", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuerySchemaRequestDto" } } } }, "responses": { "200": { "description": "Parameter schema for the specified provider query" } }, "tags": [ "Provider Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/provider/analytics/executions": { "post": { "operationId": "ProviderAnalyticsUiController_executeQuery", "summary": "Execute a single provider analytics query", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteAnalyticsQueryDto" } } } }, "responses": { "200": { "description": "Provider analytics query execution result" } }, "tags": [ "Provider Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/provider/analytics/execute-multiple": { "post": { "operationId": "ProviderAnalyticsUiController_executeMultipleQueries", "summary": "Execute multiple provider analytics queries in parallel", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteMultipleQueriesDto" } } } }, "responses": { "200": { "description": "Results from multiple provider analytics queries" } }, "tags": [ "Provider Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/provider/analytics/overview": { "post": { "operationId": "ProviderAnalyticsUiController_getProviderOverview", "summary": "Get provider analytics overview", "parameters": [], "responses": { "200": { "description": "Provider analytics overview data" } }, "tags": [ "Provider Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/provider/analytics/validate": { "post": { "operationId": "ProviderAnalyticsUiController_validateParameters", "summary": "Validate parameters for a specific provider query", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateParametersDto" } } } }, "responses": { "200": { "description": "Parameter validation result" } }, "tags": [ "Provider Analytics" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/credits/balance/{customerId}": { "get": { "operationId": "CreditsUiController_getBalance", "summary": "Get customer credit balance", "description": "Returns the credit balance for a customer as abstract integer credits.", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Credit balance" } }, "tags": [ "Credits" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/credits/balances": { "get": { "operationId": "CreditsUiController_getProviderBalances", "summary": "Get all customer credit balances", "description": "Returns the latest credit balance for every customer under the authenticated provider, plus a grand total.", "parameters": [], "responses": { "200": { "description": "Per-customer balances and grand total" } }, "tags": [ "Credits" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/credits/ledger": { "get": { "operationId": "CreditsUiController_getLedger", "summary": "List credit ledger entries", "description": "Returns paginated credit ledger entries for the authenticated provider.", "parameters": [ { "name": "customerId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "schema": { "enum": [ "USAGE", "TOPUP", "GRANT", "REFUND", "ADJUSTMENT" ], "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Start date (ISO 8601)", "schema": { "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date (ISO 8601)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Max results (default 50, max 1000)", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Offset for pagination (default 0)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Paginated list of credit ledger entries" } }, "tags": [ "Credits" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/credits/ledger/{customerId}": { "get": { "operationId": "CreditsUiController_getCustomerLedger", "summary": "List credit ledger entries for a customer", "description": "Returns paginated credit ledger entries for a specific customer.", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer identifier", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "schema": { "enum": [ "USAGE", "TOPUP", "GRANT", "REFUND", "ADJUSTMENT" ], "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Start date (ISO 8601)", "schema": { "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date (ISO 8601)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Paginated list of credit ledger entries for the customer" } }, "tags": [ "Credits" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/webhooks": { "get": { "operationId": "WebhookUiController_list", "summary": "List webhook endpoints", "parameters": [], "responses": { "200": { "description": "List of webhook endpoints for the provider" } }, "tags": [ "ui:webhooks" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "WebhookUiController_create", "summary": "Create a webhook endpoint", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointZodDto" } } } }, "responses": { "201": { "description": "Webhook endpoint created successfully" }, "400": { "description": "Invalid webhook endpoint data" } }, "tags": [ "ui:webhooks" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/webhooks/{id}": { "put": { "operationId": "WebhookUiController_update", "summary": "Update a webhook endpoint", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook endpoint ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointZodDto" } } } }, "responses": { "200": { "description": "Webhook endpoint updated successfully" }, "400": { "description": "Invalid webhook endpoint data" }, "404": { "description": "Webhook endpoint not found" } }, "tags": [ "ui:webhooks" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "WebhookUiController_remove", "summary": "Delete a webhook endpoint", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook endpoint ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook endpoint deleted successfully" }, "404": { "description": "Webhook endpoint not found" } }, "tags": [ "ui:webhooks" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/webhooks/{id}/status": { "patch": { "operationId": "WebhookUiController_setStatus", "summary": "Set webhook endpoint status (active/disabled)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook endpoint ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetWebhookStatusDto" } } } }, "responses": { "200": { "description": "Webhook endpoint status updated" }, "400": { "description": "Invalid status value" }, "404": { "description": "Webhook endpoint not found" } }, "tags": [ "ui:webhooks" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/webhooks/{id}/test": { "post": { "operationId": "WebhookUiController_sendTest", "summary": "Send a test event to a webhook endpoint", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook endpoint ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test event sent successfully" }, "404": { "description": "Webhook endpoint not found" } }, "tags": [ "ui:webhooks" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/webhooks/{id}/reveal": { "get": { "operationId": "WebhookUiController_revealSecret", "summary": "Reveal the signing secret for a webhook endpoint", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook endpoint ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook signing secret revealed" }, "404": { "description": "Webhook endpoint not found" } }, "tags": [ "ui:webhooks" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/webhooks/debug/recent-deliveries": { "get": { "operationId": "WebhookUiController_listRecentDeliveries", "summary": "List recent webhook deliveries for debugging (owner/admin only, production-gated)", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of deliveries to return (1-100, default 20)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Recent webhook deliveries" }, "403": { "description": "Forbidden for non-owner/admin users" }, "404": { "description": "Endpoint disabled in this environment" } }, "tags": [ "ui:webhooks" ], "security": [ { "bearer": [] } ] } }, "/v1/webhook_endpoints": { "post": { "operationId": "WebhookController_create", "summary": "Create a webhook endpoint (API Key)", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointDto" } } } }, "responses": { "201": { "description": "Webhook endpoint created successfully" }, "400": { "description": "Invalid webhook endpoint data" } }, "tags": [ "webhook_endpoints" ], "security": [ { "bearer": [] }, { "api_key": [] } ] }, "get": { "operationId": "WebhookController_list", "summary": "List webhook endpoints (API Key)", "parameters": [], "responses": { "200": { "description": "List of webhook endpoints for the provider" } }, "tags": [ "webhook_endpoints" ], "security": [ { "bearer": [] }, { "api_key": [] } ] } }, "/v1/webhook_endpoints/{id}": { "delete": { "operationId": "WebhookController_delete", "summary": "Delete webhook endpoint (API Key)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook endpoint ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook endpoint deleted successfully" }, "404": { "description": "Webhook endpoint not found" } }, "tags": [ "webhook_endpoints" ], "security": [ { "bearer": [] }, { "api_key": [] } ] }, "put": { "operationId": "WebhookController_update", "summary": "Update webhook endpoint (API Key)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook endpoint ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointDto" } } } }, "responses": { "200": { "description": "Webhook endpoint updated successfully" }, "400": { "description": "Invalid webhook endpoint data" }, "404": { "description": "Webhook endpoint not found" } }, "tags": [ "webhook_endpoints" ], "security": [ { "bearer": [] }, { "api_key": [] } ] } }, "/v1/customer/webhook_endpoints": { "post": { "operationId": "WebhookCustomerController_create", "summary": "Create a webhook endpoint (Customer)", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointDto" } } } }, "responses": { "201": { "description": "Webhook endpoint created successfully" }, "400": { "description": "Invalid webhook endpoint data" } }, "tags": [ "customer_webhooks" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "WebhookCustomerController_list", "summary": "List webhook endpoints (Customer)", "parameters": [], "responses": { "200": { "description": "List of webhook endpoints for the provider" } }, "tags": [ "customer_webhooks" ], "security": [ { "bearer": [] } ] } }, "/v1/customer/webhook_endpoints/{id}": { "delete": { "operationId": "WebhookCustomerController_delete", "summary": "Delete webhook endpoint (Customer)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook endpoint ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook endpoint deleted successfully" }, "404": { "description": "Webhook endpoint not found" } }, "tags": [ "customer_webhooks" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "WebhookCustomerController_update", "summary": "Update webhook endpoint (Customer)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook endpoint ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointDto" } } } }, "responses": { "200": { "description": "Webhook endpoint updated successfully" }, "400": { "description": "Invalid webhook endpoint data" }, "404": { "description": "Webhook endpoint not found" } }, "tags": [ "customer_webhooks" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/wallets": { "get": { "operationId": "WalletUiController_getWallet", "summary": "Get wallet information for the authenticated user", "description": "Retrieves the wallet information including balance, currency, and transaction history for the authenticated user.", "parameters": [], "responses": { "200": { "description": "Wallet information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Wallet ID" }, "userId": { "type": "string", "description": "User ID" }, "balance": { "type": "number", "description": "Current wallet balance" }, "currency": { "type": "string", "description": "Wallet currency" }, "createdAt": { "type": "string", "format": "date-time", "description": "Wallet creation date" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date" } } } } } }, "401": { "description": "Unauthorized - invalid or missing authentication token" } }, "tags": [ "Wallet" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/wallets/stats": { "get": { "operationId": "WalletUiController_getWalletStats", "summary": "Get wallet statistics for the authenticated user", "description": "Retrieves comprehensive wallet statistics including transaction counts, total volume, and performance metrics.", "parameters": [], "responses": { "200": { "description": "Wallet statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalTransactions": { "type": "number", "description": "Total number of transactions" }, "totalVolume": { "type": "number", "description": "Total transaction volume" }, "averageTransaction": { "type": "number", "description": "Average transaction amount" }, "lastTransactionDate": { "type": "string", "format": "date-time", "description": "Date of last transaction" }, "monthlyStats": { "type": "object", "properties": { "currentMonth": { "type": "number", "description": "Transactions this month" }, "previousMonth": { "type": "number", "description": "Transactions last month" } } } } } } } }, "401": { "description": "Unauthorized - invalid or missing authentication token" } }, "tags": [ "Wallet" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/accounts": { "get": { "operationId": "AccountsUiController_list", "summary": "List accounts", "description": "Retrieves all product accounts for the authenticated provider.", "parameters": [ { "name": "entityType", "required": false, "in": "query", "description": "Filter by entity type", "schema": { "enum": [ "product", "all" ], "type": "string" } }, { "name": "includeTransactions", "required": false, "in": "query", "description": "Include recent transactions in response", "schema": { "type": "boolean" } }, { "name": "includePurchases", "required": false, "in": "query", "description": "Include purchases in response", "schema": { "type": "boolean" } }, { "name": "transactionLimit", "required": false, "in": "query", "description": "Limit number of transactions per account", "schema": { "type": "number" } }, { "name": "purchaseLimit", "required": false, "in": "query", "description": "Limit number of purchases per account", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List of accounts retrieved successfully", "content": { "application/json": { "schema": { "type": "array" } } } } }, "tags": [ "Accounts" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/accounts/{entityId}": { "get": { "operationId": "AccountsUiController_get", "summary": "Get account by entity ID", "description": "Retrieves a specific account by entity ID (product).", "parameters": [ { "name": "entityId", "required": true, "in": "path", "description": "Entity ID (product)", "schema": { "type": "string" } }, { "name": "entityType", "required": false, "in": "query", "description": "Entity type (always product)", "schema": { "enum": [ "product" ], "type": "string" } }, { "name": "includeTransactions", "required": false, "in": "query", "description": "Include recent transactions in response", "schema": { "type": "boolean" } }, { "name": "includePurchases", "required": false, "in": "query", "description": "Include purchases in response", "schema": { "type": "boolean" } }, { "name": "transactionLimit", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "purchaseLimit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } } }, "tags": [ "Accounts" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/accounts/{entityId}/stats": { "get": { "operationId": "AccountsUiController_getStats", "summary": "Get account statistics", "description": "Retrieves statistics (balance, transaction count, last activity) for a specific account.", "parameters": [ { "name": "entityId", "required": true, "in": "path", "description": "Entity ID (product)", "schema": { "type": "string" } }, { "name": "entityType", "required": false, "in": "query", "description": "Entity type (always product)", "schema": { "enum": [ "product" ], "type": "string" } } ], "responses": { "200": { "description": "Account statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } } }, "tags": [ "Accounts" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/preferences/modes": { "get": { "operationId": "PreferencesUiController_getThemeMode", "summary": "Get current user theme mode", "parameters": [], "responses": { "200": { "description": "Theme mode retrieved successfully" } }, "tags": [ "UI Management" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "PreferencesUiController_updateThemeMode", "summary": "Update current user theme mode", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateThemePreferenceZodDto" } } } }, "responses": { "200": { "description": "Theme mode updated successfully" } }, "tags": [ "UI Management" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/preferences/theme": { "get": { "operationId": "PreferencesUiController_getTheme", "summary": "Get shared brand theme for all hosted pages", "description": "Returns the unified theme configuration used across checkout, customer portal, and OAuth pages", "parameters": [], "responses": { "200": { "description": "Brand theme retrieved successfully" } }, "tags": [ "UI Management" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "PreferencesUiController_updateTheme", "summary": "Update shared brand theme for all hosted pages", "description": "Updates the unified theme configuration used across checkout, customer portal, and OAuth pages", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBrandThemeZodDto" } } } }, "responses": { "200": { "description": "Brand theme updated successfully" } }, "tags": [ "UI Management" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/preferences/theme/logo": { "post": { "operationId": "PreferencesUiController_uploadThemeLogo", "summary": "Upload hosted-page logo", "description": "Uploads a provider logo asset and returns a URL that can be saved in shared hosted page settings.", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "logo": { "type": "string", "format": "binary" } }, "required": [ "logo" ] } } } }, "responses": { "201": { "description": "Logo uploaded successfully" } }, "tags": [ "UI Management" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/form-configs": { "get": { "operationId": "FormConfigsUiController_getFormConfig", "summary": "Get form configuration", "description": "Returns form field configuration based on form name, business type, and country. Used to dynamically render forms in the frontend.", "parameters": [ { "name": "name", "required": true, "in": "query", "description": "Form name to retrieve configuration for", "schema": { "enum": [ "business-type", "individual-info", "company-info", "address", "person", "bank-account", "documents", "terms", "provider-settings" ], "type": "string" } }, { "name": "businessType", "required": false, "in": "query", "description": "Business type context", "schema": { "enum": [ "individual", "company" ], "type": "string" } }, { "name": "country", "required": false, "in": "query", "description": "Country code (ISO 3166-1 alpha-2, e.g., \"US\", \"GB\", \"DE\")", "schema": { "type": "string" } }, { "name": "personType", "required": false, "in": "query", "description": "Person type (for person form)", "schema": { "enum": [ "representative", "owner", "director", "executive" ], "type": "string" } } ], "responses": { "200": { "description": "Form configuration" }, "400": { "description": "Invalid form name or parameters" } }, "tags": [ "Form Configs" ] } }, "/v1/ui/form-configs/wizard-sequence": { "get": { "operationId": "FormConfigsUiController_getWizardSequence", "summary": "Get wizard step sequence", "description": "Returns the ordered list of form names for a wizard based on business type", "parameters": [ { "name": "businessType", "required": true, "in": "query", "description": "Business type to get wizard sequence for", "schema": { "enum": [ "individual", "company" ], "type": "string" } } ], "responses": { "200": { "description": "Array of form names in sequence order" } }, "tags": [ "Form Configs" ] } }, "/v1/preregistrations": { "post": { "operationId": "PreregistrationsController_create", "summary": "Submit a preregistration from the get-started form", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePreregistrationZodDto" } } } }, "responses": { "201": { "description": "Preregistration submitted successfully" }, "400": { "description": "Validation error" } }, "tags": [ "Preregistrations" ] } }, "/v1/ui/financials/pnl": { "get": { "operationId": "FinancialsUiController_getPnL", "summary": "Get revenue summary data", "parameters": [ { "name": "period", "required": false, "in": "query", "schema": { "enum": [ "this-month", "last-month", "q1-2026", "last-6-months" ], "type": "string" } } ], "responses": { "200": { "description": "Revenue summary data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueResponseDto" } } } } }, "tags": [ "Financials" ] } }, "/v1/ui/financials/cashflow": { "get": { "operationId": "FinancialsUiController_getCashFlow", "summary": "Get balance & reconciliation data", "parameters": [ { "name": "period", "required": false, "in": "query", "schema": { "enum": [ "this-month", "last-month", "q1-2026", "last-6-months" ], "type": "string" } } ], "responses": { "200": { "description": "Balance & reconciliation data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponseDto" } } } } }, "tags": [ "Financials" ] } }, "/v1/ui/financials/products": { "get": { "operationId": "FinancialsUiController_getRevenueByProduct", "summary": "Get revenue by product", "parameters": [ { "name": "period", "required": false, "in": "query", "schema": { "enum": [ "this-month", "last-month", "q1-2026", "last-6-months" ], "type": "string" } } ], "responses": { "200": { "description": "Revenue by product data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueByProductResponseDto" } } } } }, "tags": [ "Financials" ] } }, "/v1/ui/financials/ledger": { "get": { "operationId": "FinancialsUiController_getLedger", "summary": "Get general ledger entries", "parameters": [ { "name": "period", "required": false, "in": "query", "schema": { "enum": [ "this-month", "last-month", "q1-2026", "last-6-months" ], "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "enum": [ "date", "credit", "description" ], "type": "string" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "description": "General ledger entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerResponseDto" } } } } }, "tags": [ "Financials" ] } }, "/v1/ui/operation/dashboard/metrics": { "get": { "operationId": "SuperAdminController_getDashboardMetrics", "summary": "Key business metrics (provider/customer/purchase counts, GMV, success rate)", "parameters": [ { "name": "environment", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dashboard metrics" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/dashboard/attention": { "get": { "operationId": "SuperAdminController_getDashboardAttention", "summary": "Items requiring operator attention", "parameters": [ { "name": "environment", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Attention items with counts" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/dashboard/transactions": { "get": { "operationId": "SuperAdminController_getDashboardTransactions", "summary": "Daily transaction volume and payment health (last 30 days)", "parameters": [ { "name": "environment", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction volume chart data and health stats" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/dashboard/growth": { "get": { "operationId": "SuperAdminController_getDashboardGrowth", "summary": "Platform growth charts (provider/customer growth, status breakdown)", "parameters": [ { "name": "environment", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Growth time-series and status breakdown" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/dashboard/activity": { "get": { "operationId": "SuperAdminController_getDashboardActivity", "summary": "Recent audit log entries", "parameters": [], "responses": { "200": { "description": "Last 15 audit log entries" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/accounts": { "get": { "operationId": "SuperAdminController_searchAccounts", "summary": "Search user and provider accounts", "parameters": [ { "name": "q", "required": false, "in": "query", "description": "Search by email, ID, or name", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by user type", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List of matching accounts" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/accounts/{id}": { "get": { "operationId": "SuperAdminController_getAccountDetail", "summary": "Get full account details", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account details" }, "404": { "description": "Account not found" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/accounts/{id}/status": { "patch": { "operationId": "SuperAdminController_updateAccountStatus", "summary": "Update account status (suspend/reactivate)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountStatusDto" } } } }, "responses": { "200": { "description": "Status updated" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/accounts/{id}/delete-confirmation": { "post": { "operationId": "SuperAdminController_requestDeleteConfirmation", "summary": "Generate a deletion confirmation token", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmation token generated" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/accounts/{id}/soft-delete": { "post": { "operationId": "SuperAdminController_softDeleteAccount", "summary": "Soft-delete an account", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account soft-deleted" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/accounts/{id}/hard-delete": { "post": { "operationId": "SuperAdminController_hardDeleteAccount", "summary": "Hard-delete an account (requires confirmation token)", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HardDeleteAccountDto" } } } }, "responses": { "200": { "description": "Account permanently deleted" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/impersonation": { "post": { "operationId": "SuperAdminController_startImpersonation", "summary": "Start an impersonation session for a user", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartImpersonationDto" } } } }, "responses": { "201": { "description": "Impersonation session started" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/impersonation/{sessionId}/end": { "post": { "operationId": "SuperAdminController_endImpersonation", "summary": "End an impersonation session", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "description": "Impersonation session ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Impersonation session ended" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/audit-log": { "get": { "operationId": "SuperAdminController_getAuditLog", "summary": "View audit log", "parameters": [ { "name": "actorId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "action", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "targetId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "targetType", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Audit log entries" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/metrics": { "get": { "operationId": "SuperAdminController_getMetrics", "summary": "Get Prometheus metrics as JSON", "parameters": [], "responses": { "200": { "description": "Metrics data" } }, "tags": [ "Super Admin" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/preregistrations": { "get": { "operationId": "SuperAdminPreregistrationsController_listPreregistrations", "summary": "List preregistrations", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "q", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Paginated preregistrations list" } }, "tags": [ "Super Admin - Preregistrations" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/preregistrations/{id}/status": { "patch": { "operationId": "SuperAdminPreregistrationsController_updateStatus", "summary": "Update preregistration status", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Preregistration ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePreregistrationStatusDto" } } } }, "responses": { "200": { "description": "Status updated" } }, "tags": [ "Super Admin - Preregistrations" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/preregistrations/{id}/convert": { "post": { "operationId": "SuperAdminPreregistrationsController_convertToProvider", "summary": "Convert a preregistration to a provider account", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Preregistration ID", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Provider account created" } }, "tags": [ "Super Admin - Preregistrations" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/providers": { "get": { "operationId": "SuperAdminProvidersController_listProviders", "summary": "List all providers", "parameters": [ { "name": "environment", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Providers list" } }, "tags": [ "Super Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/providers/{providerId}": { "get": { "operationId": "SuperAdminProvidersController_getProvider", "summary": "Get provider detail", "parameters": [ { "name": "environment", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "providerId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Provider detail" } }, "tags": [ "Super Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/providers/{providerId}/products": { "get": { "operationId": "SuperAdminProvidersController_getProducts", "summary": "Get products for a provider", "parameters": [ { "name": "environment", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "providerId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Products list" } }, "tags": [ "Super Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/providers/{providerId}/customers": { "get": { "operationId": "SuperAdminProvidersController_getCustomers", "summary": "Get customers for a provider", "parameters": [ { "name": "environment", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "providerId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Customers list" } }, "tags": [ "Super Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/providers/{providerId}/purchases": { "get": { "operationId": "SuperAdminProvidersController_getPurchases", "summary": "Get purchases for a provider", "parameters": [ { "name": "environment", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "providerId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "productId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "customerId", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Purchases list" } }, "tags": [ "Super Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/providers/{providerId}/transactions": { "get": { "operationId": "SuperAdminProvidersController_getTransactions", "summary": "Get transactions for a provider", "parameters": [ { "name": "environment", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "providerId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "fromDate", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "toDate", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Transactions list" } }, "tags": [ "Super Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/providers/{providerId}/users": { "get": { "operationId": "SuperAdminProvidersController_getProviderUsers", "summary": "Get users linked to a provider", "parameters": [ { "name": "environment", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "providerId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Provider users" } }, "tags": [ "Super Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/providers/{providerId}/meters": { "get": { "operationId": "SuperAdminProvidersController_getMeters", "summary": "Get meters for a provider", "parameters": [ { "name": "environment", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "providerId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Meters list" } }, "tags": [ "Super Admin - Providers" ], "security": [ { "bearer": [] } ] } }, "/v1/ui/operation/providers/{providerId}/usage": { "get": { "operationId": "SuperAdminProvidersController_getUsage", "summary": "Get usage data grouped by meter for a provider", "parameters": [ { "name": "environment", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "providerId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "from", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "to", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage data" } }, "tags": [ "Super Admin - Providers" ], "security": [ { "bearer": [] } ] } } }, "info": { "title": "SolvaPay REST API", "description": "The SolvaPay REST API specification", "version": "1.0", "contact": {} }, "tags": [], "servers": [], "components": { "securitySchemes": { "OAuth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.solvapay.com/v1/customer/auth/authorize", "tokenUrl": "https://api.solvapay.com/v1/customer/auth/token", "scopes": { "openid": "OpenID Connect scope", "profile": "Profile information", "email": "Email address" } } } } }, "schemas": { "TrackAnalyticsEventDto": { "type": "object", "properties": { "event": { "type": "string", "minLength": 1 }, "properties": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "userId": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "event", "properties" ] }, "CreateNotificationZodDto": { "type": "object", "properties": { "userId": { "type": "string" }, "title": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "info", "success", "warning", "error", "payment", "transaction", "system" ], "x-enumNames": [ "INFO", "SUCCESS", "WARNING", "ERROR", "PAYMENT", "TRANSACTION", "SYSTEM" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "x-enumNames": [ "LOW", "MEDIUM", "HIGH", "URGENT" ] }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "actionUrl": { "type": "string" }, "actionText": { "type": "string" }, "expiresAt": {}, "environment": { "type": "string", "enum": [ "sandbox", "live" ] } }, "required": [ "title", "message", "metadata" ] }, "BulkCreateNotificationDto": { "type": "object", "properties": { "userIds": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }, "notification": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "info", "success", "warning", "error", "payment", "transaction", "system" ], "x-enumNames": [ "INFO", "SUCCESS", "WARNING", "ERROR", "PAYMENT", "TRANSACTION", "SYSTEM" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "x-enumNames": [ "LOW", "MEDIUM", "HIGH", "URGENT" ] }, "metadata": { "type": "object", "additionalProperties": {} }, "actionUrl": { "type": "string" }, "actionText": { "type": "string" }, "expiresAt": {}, "environment": { "type": "string", "enum": [ "sandbox", "live" ] } }, "selfRequired": true } }, "required": [ "userIds", "notification" ] }, "BroadcastNotificationDto": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "info", "success", "warning", "error", "payment", "transaction", "system" ], "x-enumNames": [ "INFO", "SUCCESS", "WARNING", "ERROR", "PAYMENT", "TRANSACTION", "SYSTEM" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "x-enumNames": [ "LOW", "MEDIUM", "HIGH", "URGENT" ] }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "actionUrl": { "type": "string" }, "actionText": { "type": "string" }, "expiresAt": {}, "environment": { "type": "string", "enum": [ "sandbox", "live" ] } }, "required": [ "title", "message", "metadata" ] }, "UpdateNotificationDto": { "type": "object", "properties": { "isRead": { "type": "boolean" }, "isArchived": { "type": "boolean" } } }, "BulkUpdateNotificationDto": { "type": "object", "properties": { "notificationIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "action": { "type": "string", "enum": [ "mark-read", "mark-all-read", "archive" ] } }, "required": [ "action" ] }, "UpdateProviderUiDto": { "type": "object", "properties": { "legalEntity": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "line3": { "type": "string" }, "city": { "type": "string" }, "stateOrCounty": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" } } }, "bankAccount": { "type": "object", "properties": { "country": { "type": "string" }, "currency": { "type": "string" }, "accountHolderName": { "type": "string" }, "accountHolderType": { "type": "string", "enum": [ "individual", "company" ] }, "iban": { "type": "string" }, "bic": { "type": "string" }, "routingNumber": { "type": "string" }, "sortCode": { "type": "string" }, "bankCode": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" } } }, "companyNumber": { "type": "string" }, "taxId": { "type": "string" }, "vatNumber": { "type": "string" }, "mainActivity": { "type": "string" }, "additionalActivities": { "type": "array", "items": { "type": "string" } }, "personIds": { "type": "array", "items": { "type": "string" } }, "people": { "type": "array", "items": {} } }, "selfRequired": false }, "description": { "type": "string" }, "website": { "type": "string" }, "businessType": { "type": "string", "enum": [ "individual", "company" ] }, "businessEmail": { "type": "string", "format": "email" }, "supportEmail": { "type": "string", "format": "email" }, "telephone": { "type": "string" }, "supportTelephone": { "type": "string" }, "defaultCurrency": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "tosAcceptance": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "acceptedAt": {}, "ipAddress": { "type": "string" }, "userAgent": { "type": "string" } }, "selfRequired": false }, "theme": {} }, "required": [ "legalEntity", "metadata", "tosAcceptance" ] }, "SwitchEnvironmentDto": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "copyProducts": { "type": "boolean" }, "confirmProductCopyDecision": { "type": "boolean" } }, "required": [ "environment" ] }, "ResetOnboardingDto": { "type": "object", "properties": { "deleteProducts": { "type": "boolean" } } }, "CreateInvitationsDto": { "type": "object", "properties": { "emails": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "email" } }, "roles": { "type": "array", "items": { "type": "string" } } }, "required": [ "emails" ] }, "TransferOwnershipDto": { "type": "object", "properties": { "newOwnerId": { "type": "string", "minLength": 1 } }, "required": [ "newOwnerId" ] }, "RemoveUserDto": { "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ] }, "UpdateUserRoleDto": { "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } }, "required": [ "userId", "role" ] }, "CreateProviderAdminDto": { "type": "object", "properties": { "legalEntity": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "line3": { "type": "string" }, "city": { "type": "string" }, "stateOrCounty": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" } } }, "bankAccount": { "type": "object", "properties": { "country": { "type": "string" }, "currency": { "type": "string" }, "accountHolderName": { "type": "string" }, "accountHolderType": { "type": "string", "enum": [ "individual", "company" ] }, "iban": { "type": "string" }, "bic": { "type": "string" }, "routingNumber": { "type": "string" }, "sortCode": { "type": "string" }, "bankCode": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" } } }, "companyNumber": { "type": "string" }, "mainActivity": { "type": "string" }, "additionalActivities": { "type": "array", "items": { "type": "string" } }, "personIds": { "type": "array", "items": { "type": "string" } }, "people": { "type": "array", "items": {} } }, "selfRequired": false }, "description": { "type": "string" }, "website": { "type": "string" }, "businessType": { "type": "string", "enum": [ "individual", "company" ] }, "businessEmail": { "type": "string", "format": "email" }, "supportEmail": { "type": "string", "format": "email" }, "telephone": { "type": "string" }, "supportTelephone": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "reference": { "type": "string" }, "defaultCurrency": { "type": "string" } }, "required": [ "legalEntity", "metadata" ] }, "UpdateProviderAdminDto": { "type": "object", "properties": { "legalEntity": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "line3": { "type": "string" }, "city": { "type": "string" }, "stateOrCounty": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" } } }, "bankAccount": { "type": "object", "properties": { "country": { "type": "string" }, "currency": { "type": "string" }, "accountHolderName": { "type": "string" }, "accountHolderType": { "type": "string", "enum": [ "individual", "company" ] }, "iban": { "type": "string" }, "bic": { "type": "string" }, "routingNumber": { "type": "string" }, "sortCode": { "type": "string" }, "bankCode": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" } } }, "companyNumber": { "type": "string" }, "mainActivity": { "type": "string" }, "additionalActivities": { "type": "array", "items": { "type": "string" } }, "personIds": { "type": "array", "items": { "type": "string" } }, "people": { "type": "array", "items": {} } }, "selfRequired": false }, "description": { "type": "string" }, "website": { "type": "string" }, "businessType": { "type": "string", "enum": [ "individual", "company" ] }, "businessEmail": { "type": "string", "format": "email" }, "supportEmail": { "type": "string", "format": "email" }, "telephone": { "type": "string" }, "supportTelephone": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "defaultCurrency": { "type": "string" }, "paymentProcessor": { "type": "object", "properties": { "accountId": { "type": "string" }, "accountType": { "type": "string", "enum": [ "standard", "express", "custom" ] }, "status": { "type": "string" }, "chargesEnabled": { "type": "boolean" }, "payoutsEnabled": { "type": "boolean" }, "requirements": {}, "createdAt": {}, "updatedAt": {} }, "selfRequired": false }, "tosAcceptance": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "acceptedAt": {}, "ipAddress": { "type": "string" }, "userAgent": { "type": "string" } }, "selfRequired": false } }, "required": [ "legalEntity", "metadata", "paymentProcessor", "tosAcceptance" ] }, "UpdateProviderStatusDto": { "type": "object", "properties": { "status": { "type": "string", "minLength": 1 }, "reason": { "type": "string" } }, "required": [ "status" ] }, "CreateSecretKey": { "type": "object", "properties": {} }, "CreateUserAdminDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "type": { "type": "string", "enum": [ "provider", "admin", "super_admin" ], "x-enumNames": [ "PROVIDER", "ADMIN", "SUPER_ADMIN" ] }, "providerId": { "type": "string" }, "providerRole": { "type": "string", "enum": [ "owner", "admin", "member" ], "x-enumNames": [ "OWNER", "ADMIN", "MEMBER" ] } }, "required": [ "name", "email", "type" ] }, "UpdateUserAdminDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "type": { "type": "string", "enum": [ "provider", "admin", "super_admin" ], "x-enumNames": [ "PROVIDER", "ADMIN", "SUPER_ADMIN" ] }, "providerId": { "type": "string" }, "providerRole": { "type": "string", "enum": [ "owner", "admin", "member" ], "x-enumNames": [ "OWNER", "ADMIN", "MEMBER" ] }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false } }, "required": [ "metadata" ] }, "UpdateUserStatusDto": { "type": "object", "properties": { "status": { "type": "string", "minLength": 1 }, "reason": { "type": "string" } }, "required": [ "status" ] }, "UpdateProfileZodDto": { "type": "object", "properties": { "name": { "type": "string" }, "timezone": { "type": "string" }, "preferences": { "type": "object", "additionalProperties": {}, "selfRequired": false } }, "required": [ "preferences" ] }, "UpdatePreferencesZodDto": { "type": "object", "properties": { "preferences": { "type": "object", "additionalProperties": {}, "selfRequired": false } }, "required": [ "preferences" ] }, "RequestEmailChangeZodDto": { "type": "object", "properties": { "newEmail": { "type": "string", "format": "email" } }, "required": [ "newEmail" ] }, "VerifyEmailChangeZodDto": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 } }, "required": [ "code" ] }, "CreatePaymentIntentDto": { "type": "object", "properties": { "productRef": { "type": "string", "minLength": 1 }, "customerRef": { "type": "string", "minLength": 1 }, "planRef": { "type": "string", "minLength": 1 }, "pricingTier": { "type": "string" }, "purpose": { "type": "string", "enum": [ "product", "credit_topup", "usage_billing" ], "default": "product" }, "amount": { "type": "integer", "minimum": 100, "exclusiveMinimum": false, "maximum": 10000000, "exclusiveMaximum": false }, "currency": { "type": "string" }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "customerRef" ] }, "UpdateCheckoutSessionPlanDto": { "type": "object", "properties": { "planRef": { "type": "string", "minLength": 1 } }, "required": [ "planRef" ] }, "SelectTopupAmountDto": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 100, "exclusiveMinimum": false, "maximum": 10000000, "exclusiveMaximum": false } }, "required": [ "amount" ] }, "CreateCheckoutSessionRequest": { "type": "object", "properties": { "customerRef": { "type": "string", "minLength": 1 }, "productRef": { "type": "string", "minLength": 1 }, "planRef": { "type": "string" }, "returnUrl": { "type": "string" }, "purpose": { "type": "string", "enum": [ "credit_topup" ] } }, "required": [ "customerRef" ] }, "CreateUiCheckoutSessionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Checkout session ID", "example": "507f1f77bcf86cd799439011" }, "sessionId": { "type": "string", "description": "Public session ID used in checkout URL", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" }, "amount": { "type": "number", "description": "Amount in cents", "example": 2999 }, "currency": { "type": "string", "description": "Currency code", "example": "USD" }, "status": { "type": "string", "description": "Session status", "example": "active" }, "checkoutUrl": { "type": "string", "description": "Checkout URL to open the checkout page", "example": "https://solvapay.com/customer/checkout?id=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" } }, "required": [ "id", "sessionId", "amount", "currency", "status", "checkoutUrl" ] }, "SelectCustomerSessionProductDto": { "type": "object", "properties": { "productRef": { "type": "string", "minLength": 1 } }, "required": [ "productRef" ] }, "CancelPurchaseRequest": { "type": "object", "properties": { "reason": { "type": "string" } } }, "ProcessPaymentIntentDto": { "type": "object", "properties": { "productRef": { "type": "string", "minLength": 1 }, "customerRef": { "type": "string", "minLength": 1 }, "planRef": { "type": "string" } }, "required": [ "productRef", "customerRef" ] }, "UpdatePayoutScheduleDto": { "type": "object", "properties": { "interval": { "type": "string", "enum": [ "manual", "daily", "weekly", "monthly" ] }, "weekly_anchor": { "type": "string" }, "monthly_anchor": { "type": "number" } }, "required": [ "interval" ] }, "UpdateConnectedAccountDto": { "type": "object", "properties": { "website": { "type": "string" }, "externalAccount": { "type": "object", "properties": { "country": { "type": "string", "minLength": 1 }, "currency": { "type": "string", "minLength": 1 }, "accountHolderName": { "type": "string", "minLength": 1 }, "accountHolderType": { "type": "string", "enum": [ "individual", "company" ] }, "routingNumber": { "type": "string", "minLength": 1 }, "accountNumber": { "type": "string", "minLength": 1 } }, "selfRequired": false }, "tosAcceptance": { "type": "object", "properties": { "ip": { "type": "string", "minLength": 1 } }, "selfRequired": false } }, "required": [ "externalAccount", "tosAcceptance" ] }, "CreateStripePaymentDto": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 1 }, "connectedAccountId": { "type": "string", "minLength": 1 }, "paymentMethodId": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "customerEmail": { "type": "string" }, "customerName": { "type": "string" } }, "required": [ "amount", "currency", "connectedAccountId", "paymentMethodId", "metadata" ] }, "CreateManualPayoutDto": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false } }, "required": [ "amount", "currency", "metadata" ] }, "CreateAccountLinkDto": { "type": "object", "properties": { "returnUrl": { "type": "string", "minLength": 1 }, "refreshUrl": { "type": "string", "minLength": 1 } }, "required": [ "returnUrl", "refreshUrl" ] }, "StripeOAuthAuthorizeDto": { "type": "object", "properties": { "redirectUri": { "type": "string", "minLength": 1 }, "source": { "type": "string" } }, "required": [ "redirectUri" ] }, "StripeOAuthCallbackDto": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "state": { "type": "string", "minLength": 1 }, "redirectUri": { "type": "string" } }, "required": [ "code", "state" ] }, "CreateCheckoutSessionResponse": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Checkout session ID/token", "example": "e3f1c2d4b6a89f001122334455667788" }, "checkoutUrl": { "type": "string", "description": "Full checkout URL based on backend configuration (ready to redirect customer)", "example": "https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788" } }, "required": [ "sessionId", "checkoutUrl" ] }, "SignupDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "type": { "type": "string", "enum": [ "provider", "admin", "super_admin" ], "x-enumNames": [ "PROVIDER", "ADMIN", "SUPER_ADMIN" ] } }, "required": [ "name", "email" ] }, "AuthUserDto": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "type": { "type": "string", "enum": [ "provider", "admin", "super_admin" ] }, "emailVerified": { "type": "boolean" }, "authProvider": { "type": "string", "enum": [ "local", "google", "github", "facebook" ] }, "providerId": { "type": "string" }, "providerRole": { "type": "string" }, "preferences": { "type": "object" } }, "required": [ "id", "name", "email", "type", "emailVerified", "authProvider" ] }, "AuthResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/AuthUserDto" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresIn": { "type": "number" }, "message": { "type": "string" }, "requiresMfa": { "type": "boolean" }, "requiresMfaSetup": { "type": "boolean" } }, "required": [ "user" ] }, "LoginDto": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ] }, "VerifyLoginCodeDto": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string" } }, "required": [ "email", "code" ] }, "TwoFactorTokenDto": { "type": "object", "properties": { "twoFactorToken": { "type": "string", "minLength": 1 } }, "required": [ "twoFactorToken" ] }, "VerifyEmailDto": { "type": "object", "properties": { "emailVerificationCode": { "type": "string", "minLength": 1 } }, "required": [ "emailVerificationCode" ] }, "DynamicClientRegistrationDto": { "type": "object", "properties": { "client_name": { "type": "string", "example": "My AI Agent" }, "redirect_uris": { "example": [ "https://agent.example.com/callback" ], "type": "array", "items": { "type": "string" } }, "grant_types": { "example": [ "authorization_code", "refresh_token" ], "type": "array", "items": { "type": "string" } }, "response_types": { "example": [ "code" ], "type": "array", "items": { "type": "string" } }, "software_id": { "type": "string", "example": "agent-123" }, "software_version": { "type": "string", "example": "1.0.0" }, "logo_uri": { "type": "string", "example": "https://example.com/logo.png" }, "tos_uri": { "type": "string", "example": "https://example.com/tos" }, "policy_uri": { "type": "string", "example": "https://example.com/policy" }, "client_uri": { "type": "string", "example": "https://example.com" } }, "required": [ "client_name", "redirect_uris" ] }, "DynamicClientRegistrationResponseDto": { "type": "object", "properties": { "client_id": { "type": "string", "example": "client-id-123" }, "client_secret": { "type": "string", "example": "client-secret-456" }, "client_id_issued_at": { "type": "number", "example": 1734567890 }, "client_secret_expires_at": { "type": "number", "example": 0 }, "client_name": { "type": "string", "example": "My AI Agent" }, "redirect_uris": { "example": [ "https://agent.example.com/callback" ], "type": "array", "items": { "type": "string" } }, "grant_types": { "example": [ "authorization_code", "refresh_token" ], "type": "array", "items": { "type": "string" } }, "response_types": { "example": [ "code" ], "type": "array", "items": { "type": "string" } }, "scope": { "type": "string", "example": "openid profile email" }, "token_endpoint_auth_method": { "type": "string", "example": "client_secret_basic" } }, "required": [ "client_id", "client_secret", "client_id_issued_at", "client_secret_expires_at", "client_name", "redirect_uris", "grant_types", "response_types", "scope", "token_endpoint_auth_method" ] }, "TokenRequestDto": { "type": "object", "properties": { "grant_type": { "type": "string", "minLength": 1 }, "code": { "type": "string" }, "redirect_uri": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "code_verifier": { "type": "string" }, "refresh_token": { "type": "string" } }, "required": [ "grant_type" ] }, "RevokeTokenDto": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 }, "token_type_hint": { "type": "string" } }, "required": [ "token" ] }, "CustomerLoginDto": { "type": "object", "properties": { "client_id": { "type": "string", "minLength": 1 }, "redirect_uri": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 1 }, "scope": { "type": "string" }, "state": { "type": "string" }, "code_challenge": { "type": "string" }, "code_challenge_method": { "type": "string" }, "mcp_subdomain": { "type": "string" } }, "required": [ "client_id", "redirect_uri", "email", "password" ] }, "GoogleLoginZodDto": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "redirect_uri": { "type": "string", "minLength": 1 }, "state": { "type": "string", "minLength": 1 } }, "required": [ "code", "redirect_uri", "state" ] }, "GithubLoginZodDto": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "redirect_uri": { "type": "string", "minLength": 1 }, "state": { "type": "string", "minLength": 1 } }, "required": [ "code", "redirect_uri", "state" ] }, "ForgotPasswordDto": { "type": "object", "properties": { "client_id": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" } }, "required": [ "client_id", "email" ] }, "ResetPasswordDto": { "type": "object", "properties": { "client_id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "new_password": { "type": "string", "minLength": 1 } }, "required": [ "client_id", "token", "new_password" ] }, "OpsGoogleSessionDto": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ] }, "OpsMfaVerifyDto": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "totpCode": { "type": "string", "minLength": 1 } }, "required": [ "email", "totpCode" ] }, "CreateOAuthClientDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "redirectUris": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "userManagementMode": { "type": "string", "enum": [ "solvapay_managed", "webhook_managed" ] }, "webhookUrl": { "oneOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "customLoginPageUrl": { "oneOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] } }, "required": [ "name", "redirectUris", "webhookUrl", "customLoginPageUrl" ] }, "UpdateOAuthClientDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "redirectUris": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "userManagementMode": { "type": "string", "enum": [ "solvapay_managed", "webhook_managed" ] }, "webhookUrl": { "oneOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "customLoginPageUrl": { "oneOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "isActive": { "type": "boolean" } }, "required": [ "webhookUrl", "customLoginPageUrl" ] }, "Plan": { "type": "object", "properties": { "type": { "type": "string", "description": "Plan type exposed in SDK", "enum": [ "recurring", "one-time", "usage-based" ], "example": "recurring" }, "reference": { "type": "string", "description": "Plan reference", "example": "pln_1A2B3C4D" }, "meterRef": { "type": "string", "description": "Meter reference for usage-based plans", "example": "mtr_1A2B3C4D" }, "name": { "type": "string", "description": "Plan name", "example": "Starter" }, "description": { "type": "string", "description": "Plan description", "example": "Best for teams getting started" }, "price": { "type": "number", "description": "Plan price in cents", "example": 2999 }, "currency": { "type": "string", "description": "Currency code (ISO 4217)", "example": "USD" }, "currencySymbol": { "type": "string", "description": "Currency symbol (derived from currency)", "example": "$" }, "freeUnits": { "type": "number", "description": "Number of free units included", "example": 100 }, "setupFee": { "type": "number", "description": "One-time setup fee", "example": 500 }, "trialDays": { "type": "number", "description": "Free trial period in days", "example": 14 }, "billingCycle": { "type": "string", "description": "Billing cycle", "example": "monthly" }, "billingModel": { "type": "string", "description": "Billing model", "enum": [ "pre-paid", "post-paid" ], "example": "pre-paid" }, "creditsPerUnit": { "type": "number", "description": "Credits per usage unit (integer, >= 1)", "example": 1 }, "measures": { "type": "string", "description": "What the plan measures for usage tracking", "example": "requests" }, "limit": { "type": "number", "description": "Usage limit for the meter", "example": 10000 }, "rolloverUnusedUnits": { "type": "boolean", "description": "Whether unused units roll over to next period", "example": false }, "limits": { "type": "object", "description": "Usage limits", "additionalProperties": true }, "features": { "type": "object", "description": "Plan features", "additionalProperties": true }, "requiresPayment": { "type": "boolean", "description": "Whether payment is required", "example": true }, "isActive": { "type": "boolean", "description": "Whether the plan is active (derived from status)", "example": true }, "maxActiveUsers": { "type": "number", "description": "Maximum number of active users" }, "accessExpiryDays": { "type": "number", "description": "Access expiry in days" }, "status": { "type": "string", "description": "Plan status", "example": "active" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "type", "reference", "price", "currency", "requiresPayment", "isActive", "status", "createdAt", "updatedAt" ] }, "CreatePlanRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "recurring", "usage-based", "one-time" ] }, "billingCycle": { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ] }, "price": { "type": "number" }, "creditsPerUnit": { "type": "number" }, "currency": { "type": "string" }, "billingModel": { "type": "string", "enum": [ "pre-paid", "post-paid" ] }, "freeUnits": { "type": "number" }, "limit": { "type": "number" }, "limits": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "features": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ] }, "maxActiveUsers": { "type": "number" }, "accessExpiryDays": { "type": "number" }, "default": { "type": "boolean" } }, "required": [ "limits", "metadata", "features" ] }, "UpdatePlanRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "billingCycle": { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ] }, "price": { "type": "number" }, "creditsPerUnit": { "type": "number" }, "currency": { "type": "string" }, "billingModel": { "type": "string", "enum": [ "pre-paid", "post-paid" ] }, "freeUnits": { "type": "number" }, "limit": { "type": "number" }, "limits": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "features": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ] }, "maxActiveUsers": { "type": "number" }, "accessExpiryDays": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "default": { "type": "boolean" } }, "required": [ "limits", "features", "metadata" ] }, "CreateProductRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "productType": { "type": "string" }, "isMcpPay": { "type": "boolean" }, "config": { "type": "object", "properties": { "fulfillmentType": { "type": "string" }, "validityPeriod": { "type": "number" }, "deliveryMethod": { "type": "string" } }, "selfRequired": false }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false } }, "required": [ "name", "config", "metadata" ] }, "ProductConfigDto": { "type": "object", "properties": { "fulfillmentType": { "type": "string", "description": "Fulfillment type", "example": "digital" }, "validityPeriod": { "type": "number", "description": "Validity period in days", "example": 30 }, "deliveryMethod": { "type": "string", "description": "Delivery method", "example": "api" } } }, "SdkPlanResponse": { "type": "object", "properties": { "reference": { "type": "string", "description": "Plan reference", "example": "pln_1A2B3C4D" }, "price": { "type": "number", "description": "Plan price in cents", "example": 2999 }, "currency": { "type": "string", "description": "Currency code (ISO 4217)", "example": "USD" }, "currencySymbol": { "type": "string", "description": "Currency symbol", "example": "$" }, "setupFee": { "type": "number", "description": "One-time setup fee", "example": 500 }, "trialDays": { "type": "number", "description": "Free trial period in days", "example": 14 }, "billingCycle": { "type": "string", "description": "Billing cycle", "example": "monthly" }, "billingModel": { "type": "string", "description": "Billing model", "example": "pre-paid" }, "creditsPerUnit": { "type": "number", "description": "Credits per usage unit (integer, >= 1)", "example": 1 }, "measures": { "type": "string", "description": "What the plan measures for usage tracking", "example": "requests" }, "meterRef": { "type": "string", "description": "Meter reference for usage-based limits", "example": "mtr_1A2B3C4D" }, "limit": { "type": "number", "description": "Usage limit for the meter", "example": 10000 }, "rolloverUnusedUnits": { "type": "boolean", "description": "Whether unused units roll over to next period", "example": false }, "freeUnits": { "type": "number", "description": "Included free units", "example": 1000 }, "limits": { "type": "object", "description": "Usage limits", "additionalProperties": true }, "features": { "type": "object", "description": "Plan features", "additionalProperties": true }, "requiresPayment": { "type": "boolean", "description": "Whether payment is required", "example": true }, "isActive": { "type": "boolean", "description": "Whether the plan is active", "example": true }, "status": { "type": "string", "description": "Plan status", "example": "active" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "reference", "price", "currency", "requiresPayment", "isActive", "status", "createdAt", "updatedAt" ] }, "SdkProductResponse": { "type": "object", "properties": { "reference": { "type": "string", "description": "Product reference", "example": "prd_1A2B3C4D" }, "name": { "type": "string", "description": "Product name", "example": "AI Writing Assistant" }, "description": { "type": "string", "description": "Product description" }, "imageUrl": { "type": "string", "description": "URL to the product image" }, "productType": { "type": "string", "description": "Free-form product type" }, "status": { "type": "string", "description": "Product status", "example": "active" }, "balance": { "type": "number", "description": "Product balance in cents", "example": 0 }, "totalTransactions": { "type": "number", "description": "Total number of transactions", "example": 0 }, "isMcpPay": { "type": "boolean", "description": "Whether this product uses MCP Pay proxy", "example": false }, "config": { "description": "Product-specific configuration", "allOf": [ { "$ref": "#/components/schemas/ProductConfigDto" } ] }, "metadata": { "type": "object", "description": "Arbitrary key-value metadata", "additionalProperties": true }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" }, "plans": { "description": "Plans associated with this product", "type": "array", "items": { "$ref": "#/components/schemas/SdkPlanResponse" } }, "mcp": { "type": "object", "description": "MCP linkage details for MCP-enabled products", "additionalProperties": true, "example": { "mcpServerRef": "mcp_ABC123", "mcpSubdomain": "acme-docs", "mcpProxyUrl": "https://acme-docs.mcp.solvapay.com/mcp", "originUrl": "https://origin.example.com/mcp", "defaultPlanRef": "pln_FREE123" } } }, "required": [ "reference", "name", "status", "balance", "totalTransactions", "isMcpPay", "createdAt", "updatedAt" ] }, "UpdateProductRequest": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "productType": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended" ] }, "config": { "type": "object", "properties": { "fulfillmentType": { "type": "string" }, "validityPeriod": { "type": "number" }, "deliveryMethod": { "type": "string" } }, "selfRequired": false }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false } }, "required": [ "config", "metadata" ] }, "McpBootstrapDto": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "productType": { "type": "string" }, "originUrl": { "type": "string", "minLength": 1, "format": "uri" }, "mcpDomain": { "type": "string" }, "authHeaderName": { "type": "string" }, "authApiKey": { "type": "string" }, "plans": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "price": { "type": "number", "minimum": 0, "exclusiveMinimum": false }, "currency": { "type": "string", "minLength": 1 }, "billingCycle": { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ] }, "type": { "type": "string", "enum": [ "recurring", "one-time", "usage-based" ] }, "creditsPerUnit": { "type": "number" }, "billingModel": { "type": "string", "enum": [ "pre-paid", "post-paid" ] }, "freeUnits": { "type": "number", "minimum": 0, "exclusiveMinimum": false }, "limit": { "type": "number", "minimum": 0, "exclusiveMinimum": false }, "features": { "type": "object", "additionalProperties": {} } }, "required": [ "key", "name", "price", "currency" ] } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "noPlan": { "type": "boolean" }, "planKeys": { "type": "array", "items": { "type": "string" } } }, "required": [ "name" ] } }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false } }, "required": [ "originUrl", "metadata" ] }, "McpBootstrapResult": { "type": "object", "properties": { "product": { "description": "Created product", "allOf": [ { "$ref": "#/components/schemas/SdkProductResponse" } ] }, "mcpServer": { "type": "object", "description": "Created or updated MCP server identity", "additionalProperties": true, "example": { "reference": "mcp_ABC123", "subdomain": "acme-docs", "mcpProxyUrl": "https://acme-docs.mcp.solvapay.com/mcp", "url": "https://origin.example.com/mcp", "defaultPlanRef": "pln_FREE123" } }, "planMap": { "type": "object", "description": "Resolved plan mapping by bootstrap key", "additionalProperties": true, "example": { "free": { "reference": "pln_FREE123", "name": "Free" } } }, "toolsAutoMapped": { "type": "boolean", "description": "True when tools were auto-discovered from origin because the request omitted tools", "example": true }, "autoMappedTools": { "type": "array", "description": "Auto-discovered tools used during bootstrap", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } }, "required": [ "product", "mcpServer", "planMap" ] }, "ConfigureMcpPlansDto": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "price": { "type": "number", "minimum": 0, "exclusiveMinimum": false }, "currency": { "type": "string", "minLength": 1 }, "billingCycle": { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ] }, "type": { "type": "string", "enum": [ "recurring", "one-time", "usage-based" ] }, "creditsPerUnit": { "type": "number" }, "billingModel": { "type": "string", "enum": [ "pre-paid", "post-paid" ] }, "freeUnits": { "type": "number", "minimum": 0, "exclusiveMinimum": false }, "limit": { "type": "number", "minimum": 0, "exclusiveMinimum": false }, "features": { "type": "object", "additionalProperties": {} } }, "required": [ "key", "name", "price", "currency" ] } }, "toolMapping": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "planKeys": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "planKeys" ] } } } }, "ConfigureMcpPlansResult": { "type": "object", "properties": { "product": { "description": "Updated product", "allOf": [ { "$ref": "#/components/schemas/SdkProductResponse" } ] }, "mcpServer": { "type": "object", "description": "Updated MCP server identity", "additionalProperties": true }, "planMap": { "type": "object", "description": "Resolved plan mapping by key (includes existing free plan)", "additionalProperties": true } }, "required": [ "product", "mcpServer", "planMap" ] }, "CloneProductDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } } }, "CheckProductNameDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "excludeId": { "type": "string" } }, "required": [ "name" ] }, "CreateProductUiDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "productType": { "type": "string" }, "isMcpPay": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ] }, "config": {}, "metadata": {} }, "required": [ "name" ] }, "McpBootstrapPreviewResult": { "type": "object", "properties": { "discoveredTools": { "type": "array", "description": "Discovered tools from the origin MCP server", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } }, "validation": { "type": "object", "description": "Validation status for the provided bootstrap payload", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/McpBootstrapPreviewValidationError" } } } }, "derivedName": { "type": "string", "description": "Product name derived from origin MCP metadata or hostname fallback", "example": "acme-origin-mcp" }, "derivedDescription": { "type": "string", "description": "Product description derived from origin server instructions", "example": "MCP toolkit for document retrieval and summarization." }, "metadataSource": { "type": "object", "description": "Source of derived metadata", "properties": { "name": { "type": "string", "enum": [ "request", "origin", "hostname" ] }, "description": { "type": "string", "enum": [ "request", "instructions", "none" ] } } }, "suggestedMapping": { "type": "array", "description": "Suggested default tool-to-plan mapping for UI review", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "planKey": { "type": "string" } } } } }, "required": [ "discoveredTools", "validation", "metadataSource", "suggestedMapping" ] }, "UpdateProductUiDto": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "productType": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended" ] }, "isMcpPay": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ] } } }, "CreateUsageRequest": { "type": "object", "properties": { "customerRef": { "type": "string", "minLength": 1 }, "actionType": { "type": "string", "enum": [ "transaction", "api_call", "hour", "email", "storage", "custom" ], "default": "api_call" }, "units": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 1 }, "outcome": { "type": "string", "enum": [ "success", "paywall", "fail" ], "default": "success" }, "productRef": { "type": "string" }, "purchaseRef": { "type": "string" }, "description": { "type": "string" }, "errorMessage": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "duration": { "type": "number", "minimum": 0, "exclusiveMinimum": false }, "timestamp": { "type": "string", "format": "date-time" }, "idempotencyKey": { "type": "string", "maxLength": 256 } }, "required": [ "customerRef", "metadata", "timestamp" ] }, "BulkCreateUsageRequest": { "type": "object", "properties": { "events": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "properties": { "customerRef": { "type": "string", "minLength": 1 }, "actionType": { "type": "string", "enum": [ "transaction", "api_call", "hour", "email", "storage", "custom" ], "default": "api_call" }, "units": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 1 }, "outcome": { "type": "string", "enum": [ "success", "paywall", "fail" ], "default": "success" }, "productRef": { "type": "string" }, "purchaseRef": { "type": "string" }, "description": { "type": "string" }, "errorMessage": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "duration": { "type": "number", "minimum": 0, "exclusiveMinimum": false }, "timestamp": { "type": "string", "format": "date-time" }, "idempotencyKey": { "type": "string", "maxLength": 256 } }, "required": [ "customerRef", "timestamp" ] } } }, "required": [ "events" ] }, "RecordMeterEventZodDto": { "type": "object", "properties": { "meterName": { "type": "string", "minLength": 1 }, "customerRef": { "type": "string", "minLength": 1 }, "value": { "type": "number" }, "properties": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "productRef": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "meterName", "customerRef", "properties" ] }, "RecordBulkMeterEventsZodDto": { "type": "object", "properties": { "events": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "meterName": { "type": "string", "minLength": 1 }, "customerRef": { "type": "string", "minLength": 1 }, "value": { "type": "number" }, "properties": { "type": "object", "additionalProperties": {} }, "productRef": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "meterName", "customerRef" ] } } }, "required": [ "events" ] }, "RefundTransactionDto": { "type": "object", "properties": { "originalTransactionId": { "type": "string", "minLength": 1 }, "refundAmount": { "type": "number" }, "currency": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 }, "providerId": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false } }, "required": [ "originalTransactionId", "refundAmount", "currency", "reason", "metadata" ] }, "CancelTransactionDto": { "type": "object", "properties": { "transactionRef": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 }, "providerId": { "type": "string", "minLength": 1 } }, "required": [ "transactionRef", "reason" ] }, "McpToolDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Tool name", "example": "search_documents" }, "planIds": { "description": "Plan IDs that grant access to this tool", "example": [ "pln_abc123" ], "type": "array", "items": { "type": "string" } }, "noPlan": { "type": "boolean", "description": "If true, the tool is unprotected (no purchase check or usage tracking)", "example": false }, "description": { "type": "string", "description": "Human-readable tool description", "example": "Search indexed documents" }, "isVirtual": { "type": "boolean", "description": "Whether this is a virtual platform tool handled by SolvaPay", "example": false } }, "required": [ "name" ] }, "McpServerDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Server ID", "example": "507f1f77bcf86cd799439011" }, "reference": { "type": "string", "description": "Unique server reference", "example": "mcp_abc123" }, "name": { "type": "string", "description": "Domain slug used to derive the MCP endpoint subdomain", "example": "my-mcp-server" }, "subdomain": { "type": "string", "description": "URL-safe subdomain derived from name", "example": "my-mcp-server" }, "mcpProxyUrl": { "type": "string", "description": "SolvaPay proxy URL that MCP clients connect to", "example": "https://mytelescope.mcp.solvapay.com/mcp" }, "url": { "type": "string", "description": "Origin URL of the actual MCP server", "example": "https://origin.example.com/mcp" }, "avatarUrl": { "type": "string", "description": "Avatar image URL", "example": "https://example.com/avatar.png" }, "tools": { "description": "Registered tools for this server", "type": "array", "items": { "$ref": "#/components/schemas/McpToolDto" } }, "defaultPlanId": { "type": "string", "description": "Default plan ID for tool access gating. Must belong to the linked product and be a free-tier plan (requiresPayment=false or price=0).", "example": "pln_default" }, "productId": { "type": "string", "description": "Associated product ID", "example": "507f1f77bcf86cd799439011" }, "status": { "type": "string", "description": "Server status", "example": "active", "enum": [ "active", "inactive", "suspended" ] }, "providerId": { "type": "string", "description": "Provider ID that owns this server", "example": "507f1f77bcf86cd799439011" }, "authHeaderName": { "type": "string", "description": "Custom auth header name for origin requests", "example": "X-API-Key" }, "hasAuthApiKey": { "type": "boolean", "description": "Whether an auth API key is configured", "example": true }, "totalTransactions": { "type": "number", "description": "Total number of tool-call transactions", "example": 42 }, "balance": { "type": "number", "description": "Current balance in cents", "example": 1500 } }, "required": [ "name", "subdomain", "url", "providerId" ] }, "CheckMcpNameDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "excludeId": { "type": "string" } }, "required": [ "name" ] }, "CheckBootstrapSubdomainDto": { "type": "object", "properties": { "subdomainInput": { "type": "string", "minLength": 1 } }, "required": [ "subdomainInput" ] }, "CreateMcpServerDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "url": { "type": "string", "minLength": 1 }, "avatarUrl": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "planIds": { "type": "array", "items": { "type": "string" } }, "noPlan": { "type": "boolean" }, "description": { "type": "string" }, "isVirtual": { "type": "boolean" } }, "required": [ "name" ] } }, "productId": { "type": "string", "minLength": 1 }, "defaultPlanId": { "type": "string" }, "authHeaderName": { "type": "string" }, "authApiKey": { "type": "string" } }, "required": [ "name", "url", "productId" ] }, "UpdateMcpServerDto": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "avatarUrl": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "planIds": { "type": "array", "items": { "type": "string" } }, "noPlan": { "type": "boolean" }, "description": { "type": "string" }, "isVirtual": { "type": "boolean" } }, "required": [ "name" ] } }, "defaultPlanId": { "type": "string" }, "authHeaderName": { "type": "string" }, "authApiKey": { "type": "string" } } }, "DiscoverToolsDto": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1 }, "authHeaderName": { "type": "string" }, "authApiKey": { "type": "string" } }, "required": [ "url" ] }, "PlanSnapshotDto": { "type": "object", "properties": { "reference": { "type": "string", "description": "Plan reference", "example": "pln_1A2B3C4D" }, "price": { "type": "number", "description": "Plan price in cents", "example": 2999 }, "currency": { "type": "string", "description": "Currency code", "example": "USD" }, "planType": { "type": "string", "description": "Plan type", "example": "recurring" }, "billingCycle": { "type": "string", "nullable": true, "description": "Billing cycle", "example": "monthly" }, "features": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Plan features" }, "limits": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Usage limits" }, "meterId": { "type": "string", "description": "Meter ObjectId reference", "example": "507f1f77bcf86cd799439011" }, "limit": { "type": "number", "description": "Usage limit for the meter", "example": 5000 }, "freeUnits": { "type": "number", "description": "Number of free units included", "example": 100 }, "creditsPerUnit": { "type": "number", "description": "Credits per usage unit (integer, >= 1)", "example": 1 } }, "required": [ "price", "currency", "planType" ] }, "UsageBillingDto": { "type": "object", "properties": { "used": { "type": "number", "description": "Units consumed in current period", "example": 150 }, "overageUnits": { "type": "number", "description": "Units exceeding the plan limit", "example": 0 }, "overageCost": { "type": "number", "description": "Overage cost in cents", "example": 0 }, "periodStart": { "type": "string", "description": "Period start date", "example": "2025-10-01T00:00:00Z" }, "periodEnd": { "type": "string", "description": "Period end date", "example": "2025-11-01T00:00:00Z" } }, "required": [ "used", "overageUnits", "overageCost" ] }, "PurchaseResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Purchase ID", "example": "507f1f77bcf86cd799439011" }, "reference": { "type": "string", "description": "Purchase reference", "example": "pur_1A2B3C4D" }, "customerRef": { "type": "string", "description": "Customer reference", "example": "cus_3C4D5E6F" }, "customerEmail": { "type": "string", "description": "Customer email", "example": "customer@example.com" }, "productRef": { "type": "string", "description": "Product reference", "example": "prd_1A2B3C4D" }, "productId": { "type": "string", "description": "Product ID", "example": "507f1f77bcf86cd799439012" }, "productName": { "type": "string", "description": "Product name", "example": "API Gateway Manager" }, "planSnapshot": { "description": "Plan snapshot at time of purchase (null for credit topups)", "allOf": [ { "$ref": "#/components/schemas/PlanSnapshotDto" } ] }, "status": { "type": "string", "description": "Purchase status", "example": "active" }, "amount": { "type": "number", "description": "Amount in USD cents (normalised for aggregation)", "example": 9900 }, "originalAmount": { "type": "number", "description": "Original amount in the payment currency (cents/pence)", "example": 10000 }, "currency": { "type": "string", "description": "Original payment currency code", "example": "GBP" }, "exchangeRate": { "type": "number", "description": "Exchange rate from original currency to USD", "example": 1.3082 }, "startDate": { "type": "string", "description": "Start date" }, "endDate": { "type": "string", "description": "End date" }, "paidAt": { "type": "string", "description": "Paid at timestamp" }, "usage": { "description": "Usage billing state for usage-based plans", "allOf": [ { "$ref": "#/components/schemas/UsageBillingDto" } ] }, "isRecurring": { "type": "boolean", "description": "Is recurring", "example": true }, "billingCycle": { "type": "string", "description": "Billing cycle", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, "nextBillingDate": { "type": "string", "description": "Next billing date" }, "autoRenew": { "type": "boolean", "description": "Auto-renew enabled" }, "cancelledAt": { "type": "string", "description": "Cancelled at" }, "cancellationReason": { "type": "string", "description": "Cancellation reason" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Arbitrary metadata attached to the purchase" }, "createdAt": { "type": "string", "description": "Created at" } }, "required": [ "id", "reference", "customerRef", "customerEmail", "productRef", "status", "amount", "currency", "startDate", "isRecurring", "createdAt" ] }, "SdkPlanSnapshotDto": { "type": "object", "properties": { "reference": { "type": "string", "description": "Plan reference", "example": "pln_1A2B3C4D" }, "price": { "type": "number", "description": "Plan price in cents", "example": 2999 }, "currency": { "type": "string", "description": "Currency code", "example": "USD" }, "planType": { "type": "string", "description": "Plan type", "example": "recurring" }, "billingCycle": { "type": "string", "nullable": true, "description": "Billing cycle", "example": "monthly" }, "features": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Plan features" }, "limits": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Usage limits" }, "meterRef": { "type": "string", "description": "Meter reference", "example": "mtr_1A2B3C4D" }, "limit": { "type": "number", "description": "Usage limit for the meter", "example": 5000 }, "freeUnits": { "type": "number", "description": "Number of free units included", "example": 100 }, "creditsPerUnit": { "type": "number", "description": "Credits per usage unit (integer, >= 1)", "example": 1 } }, "required": [ "price", "currency", "planType" ] }, "SdkPurchaseResponse": { "type": "object", "properties": { "reference": { "type": "string", "description": "Purchase reference", "example": "pur_1A2B3C4D" }, "customerRef": { "type": "string", "description": "Customer reference", "example": "cus_3C4D5E6F" }, "customerEmail": { "type": "string", "description": "Customer email", "example": "customer@example.com" }, "productRef": { "type": "string", "description": "Product reference", "example": "prd_1A2B3C4D" }, "productName": { "type": "string", "description": "Product name", "example": "API Gateway Manager" }, "planSnapshot": { "description": "Plan snapshot at time of purchase (null for credit topups)", "allOf": [ { "$ref": "#/components/schemas/SdkPlanSnapshotDto" } ] }, "status": { "type": "string", "description": "Purchase status", "example": "active" }, "amount": { "type": "number", "description": "Amount in USD cents (normalised for aggregation)", "example": 9900 }, "originalAmount": { "type": "number", "description": "Original amount in the payment currency (cents/pence)", "example": 10000 }, "currency": { "type": "string", "description": "Original payment currency code", "example": "GBP" }, "exchangeRate": { "type": "number", "description": "Exchange rate from original currency to USD", "example": 1.3082 }, "startDate": { "type": "string", "description": "Start date" }, "endDate": { "type": "string", "description": "End date" }, "paidAt": { "type": "string", "description": "Paid at timestamp" }, "usage": { "description": "Usage billing state for usage-based plans", "allOf": [ { "$ref": "#/components/schemas/UsageBillingDto" } ] }, "isRecurring": { "type": "boolean", "description": "Is recurring", "example": true }, "billingCycle": { "type": "string", "description": "Billing cycle", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, "nextBillingDate": { "type": "string", "description": "Next billing date" }, "autoRenew": { "type": "boolean", "description": "Auto-renew enabled" }, "cancelledAt": { "type": "string", "description": "Cancelled at" }, "cancellationReason": { "type": "string", "description": "Cancellation reason" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Arbitrary metadata attached to the purchase" }, "createdAt": { "type": "string", "description": "Created at" } }, "required": [ "reference", "customerRef", "customerEmail", "productRef", "status", "amount", "currency", "startDate", "isRecurring", "createdAt" ] }, "CheckLimitRequest": { "type": "object", "properties": { "customerRef": { "type": "string", "minLength": 1 }, "productRef": { "type": "string", "minLength": 1 }, "planRef": { "type": "string" }, "meterName": { "type": "string" }, "usageType": { "type": "string" } }, "required": [ "customerRef", "productRef" ] }, "LimitPlanItemDto": { "type": "object", "properties": { "reference": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "price": { "type": "number", "description": "Price in smallest currency unit (e.g. cents)" }, "currency": { "type": "string" }, "requiresPayment": { "type": "boolean" }, "freeUnits": { "type": "number" }, "creditsPerUnit": { "type": "number", "description": "Credits per usage unit (usage-based plans)" }, "billingModel": { "type": "string" }, "billingCycle": { "type": "string" } }, "required": [ "reference", "type", "price", "currency", "requiresPayment" ] }, "LimitBalanceDto": { "type": "object", "properties": { "creditBalance": { "type": "number", "description": "Credit balance in mils" }, "creditsPerUnit": { "type": "number", "description": "Credits per usage unit" }, "currency": { "type": "string" }, "remainingUnits": { "type": "number", "description": "Estimated whole units remaining from prepaid credit balance" } }, "required": [ "creditBalance", "creditsPerUnit", "currency" ] }, "LimitProductBriefDto": { "type": "object", "properties": { "reference": { "type": "string" }, "name": { "type": "string" } }, "required": [ "reference" ] }, "LimitResponse": { "type": "object", "properties": { "withinLimits": { "type": "boolean", "description": "Whether the customer is within their usage limits", "example": true }, "remaining": { "type": "number", "description": "Remaining usage units before hitting the limit", "example": 997 }, "checkoutSessionId": { "type": "string", "description": "Checkout session ID if payment is required", "example": "e3f1c2d4b6a89f001122334455667788" }, "checkoutUrl": { "type": "string", "description": "Checkout URL if payment is required", "example": "https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788" }, "meterName": { "type": "string", "description": "The meter name to use when tracking usage events", "example": "requests" }, "creditBalance": { "type": "number", "description": "Credit balance in mils (for pre-paid usage-based plans)" }, "creditsPerUnit": { "type": "number", "description": "Credits per usage unit (for pre-paid usage-based plans)" }, "currency": { "type": "string", "description": "ISO 4217 currency code for credit fields" }, "activationRequired": { "type": "boolean", "description": "True when the customer must activate a priced default plan before usage is allowed" }, "plans": { "description": "Active plans on the product available for activation or checkout", "type": "array", "items": { "$ref": "#/components/schemas/LimitPlanItemDto" } }, "balance": { "description": "Prepaid usage balance context when the default plan is usage-based", "allOf": [ { "$ref": "#/components/schemas/LimitBalanceDto" } ] }, "product": { "description": "Product the limit check applies to", "allOf": [ { "$ref": "#/components/schemas/LimitProductBriefDto" } ] }, "confirmationUrl": { "type": "string", "description": "Customer portal confirmation URL when activation is required (fallback when not starting checkout)" } }, "required": [ "withinLimits", "remaining" ] }, "ActivatePlanDto": { "type": "object", "properties": { "customerRef": { "type": "string" }, "productRef": { "type": "string" }, "planRef": { "type": "string" } }, "required": [ "customerRef", "productRef", "planRef" ] }, "ActivatePlanResponseDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "activated", "already_active", "topup_required", "payment_required", "invalid" ] }, "purchaseRef": { "type": "string" }, "message": { "type": "string" }, "creditBalance": { "type": "number" }, "creditsPerUnit": { "type": "number" }, "currency": { "type": "string" }, "checkoutUrl": { "type": "string" }, "checkoutSessionId": { "type": "string" } }, "required": [ "status" ] }, "CreateCustomerRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "telephone": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "externalRef": { "type": "string" } }, "required": [ "email", "metadata" ] }, "UpdateCustomerUiDto": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "telephone": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {}, "selfRequired": false }, "externalRef": { "type": "string" } }, "required": [ "metadata" ] }, "CreatePaymentFromLinkDto": { "type": "object", "properties": { "paymentLinkId": { "type": "string", "minLength": 1 }, "paymentMethodId": { "type": "string", "minLength": 1 } }, "required": [ "paymentLinkId", "paymentMethodId" ] }, "CreateCustomerSessionRequest": { "type": "object", "properties": { "customerRef": { "type": "string", "minLength": 1 }, "productRef": { "type": "string" } }, "required": [ "customerRef" ] }, "CustomerSessionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Customer session ID", "example": "507f1f77bcf86cd799439011" }, "sessionId": { "type": "string", "description": "Public session ID used in customer URL", "example": "e3f1c2d4b6a89f001122334455667788" }, "status": { "type": "string", "description": "Session status", "example": "active" }, "customerUrl": { "type": "string", "description": "Customer URL to open the customer page", "example": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788" } }, "required": [ "id", "sessionId", "status", "customerUrl" ] }, "PurchaseInfo": { "type": "object", "properties": { "reference": { "type": "string", "description": "Purchase reference", "example": "pur_1A2B3C4D" }, "productName": { "type": "string", "description": "Product name", "example": "API Gateway Manager" }, "productRef": { "type": "string", "description": "Product reference", "example": "prd_abc123" }, "status": { "type": "string", "description": "Purchase status", "example": "active" }, "startDate": { "type": "string", "description": "Start date", "example": "2025-10-27T10:00:00Z" }, "amount": { "type": "number", "description": "Amount in USD cents (normalised for aggregation)", "example": 9900 }, "originalAmount": { "type": "number", "description": "Original amount in the payment currency (minor units)", "example": 7500 }, "currency": { "type": "string", "description": "ISO 4217 currency code of the customer-facing charge", "example": "GBP" }, "exchangeRate": { "type": "number", "description": "Exchange rate from original currency to USD", "example": 1.32 }, "endDate": { "type": "string", "description": "End date of purchase", "example": "2025-11-27T10:00:00Z" }, "cancelledAt": { "type": "string", "description": "When purchase was cancelled", "example": "2025-10-28T10:00:00Z" }, "cancellationReason": { "type": "string", "description": "Reason for cancellation", "example": "Customer request" }, "planRef": { "type": "string", "description": "Plan reference from the plan snapshot, for reliable plan matching", "example": "pln_abc123" }, "planSnapshot": { "type": "object", "description": "Snapshot of the plan at time of purchase" } }, "required": [ "reference", "productName", "status", "startDate", "amount", "currency" ] }, "CustomerResponse": { "type": "object", "properties": { "reference": { "type": "string", "description": "Customer reference identifier", "example": "cus_3c4d5e6f7g8h" }, "name": { "type": "string", "description": "Customer full name", "example": "John Doe" }, "email": { "type": "string", "description": "Customer email address", "example": "customer@example.com" }, "externalRef": { "type": "string", "description": "External reference ID from your auth system (if set during creation or update)", "example": "auth_user_12345" }, "purchases": { "description": "Active purchases", "type": "array", "items": { "$ref": "#/components/schemas/PurchaseInfo" } } }, "required": [ "reference", "name", "email" ] }, "CreateCustomerSessionResponse": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Customer session ID/token", "example": "e3f1c2d4b6a89f001122334455667788" }, "customerUrl": { "type": "string", "description": "Full customer URL based on backend configuration (ready to redirect customer)", "example": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788" } }, "required": [ "sessionId", "customerUrl" ] }, "GetCustomerSessionResponse": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Customer session ID/token", "example": "e3f1c2d4b6a89f001122334455667788" }, "status": { "type": "string", "description": "Session status", "example": "active", "enum": [ "active", "expired", "used" ] }, "customerUrl": { "type": "string", "description": "Full customer URL based on backend configuration (ready to redirect customer)", "example": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788" }, "expiresAt": { "type": "string", "description": "Session expiration date", "example": "2025-01-01T12:00:00.000Z" }, "customer": { "description": "Customer object from session data", "allOf": [ { "$ref": "#/components/schemas/CustomerResponse" } ] }, "createdAt": { "type": "string", "description": "Session creation date", "example": "2025-01-01T11:45:00.000Z" }, "updatedAt": { "type": "string", "description": "Session last update date", "example": "2025-01-01T11:45:00.000Z" } }, "required": [ "sessionId", "status", "customerUrl", "expiresAt", "customer", "createdAt", "updatedAt" ] }, "UserInfoRequest": { "type": "object", "properties": { "customerRef": { "type": "string", "minLength": 1 }, "productRef": { "type": "string", "minLength": 1 } }, "required": [ "customerRef", "productRef" ] }, "UserInfoUserDto": { "type": "object", "properties": { "reference": { "type": "string", "example": "cus_3C4D5E6F" }, "name": { "type": "string", "nullable": true, "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "externalRef": { "type": "string", "nullable": true, "example": "auth_user_12345" } }, "required": [ "reference", "email" ] }, "UserInfoUsageDto": { "type": "object", "properties": { "total": { "type": "number", "example": 1000 }, "used": { "type": "number", "example": 250 }, "remaining": { "type": "number", "example": 750 }, "meterRef": { "type": "string", "nullable": true, "example": "meter_ABC123", "description": "Meter reference" }, "percentUsed": { "type": "number", "nullable": true, "example": 25 } }, "required": [ "total", "used", "remaining" ] }, "UserInfoPlanDto": { "type": "object", "properties": { "reference": { "type": "string", "example": "pln_2B3C4D5E" }, "price": { "type": "number", "description": "Price in minor currency units (e.g. cents)", "example": 2999 }, "currency": { "type": "string", "example": "USD" }, "type": { "type": "string", "example": "recurring" }, "billingCycle": { "type": "string", "nullable": true, "example": "monthly" }, "features": { "nullable": true, "type": "array", "items": { "type": "string" } }, "limits": { "type": "object", "nullable": true, "additionalProperties": true } }, "required": [ "reference", "price", "currency", "type" ] }, "UserInfoPurchaseDto": { "type": "object", "properties": { "reference": { "type": "string", "example": "pur_1A2B3C4D" }, "status": { "type": "string", "example": "active" }, "productName": { "type": "string", "example": "My API Product" }, "planType": { "type": "string", "example": "recurring" }, "startDate": { "type": "string", "nullable": true, "example": "2025-10-27T10:00:00Z" }, "endDate": { "type": "string", "nullable": true, "example": "2025-11-27T10:00:00Z" }, "usage": { "$ref": "#/components/schemas/UserInfoUsageDto" }, "plan": { "$ref": "#/components/schemas/UserInfoPlanDto" } }, "required": [ "reference", "status", "productName", "planType" ] }, "UserInfoResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Human-readable status summary", "example": "Active subscription: My API Product (25% usage consumed)" }, "verifyUrl": { "type": "string", "nullable": true, "description": "Customer portal session URL", "example": "https://solvapay.com/customer/manage?id=abc123" }, "user": { "$ref": "#/components/schemas/UserInfoUserDto" }, "purchase": { "$ref": "#/components/schemas/UserInfoPurchaseDto" } }, "required": [ "status" ] }, "QuerySchemaRequestDto": { "type": "object", "properties": { "queryName": { "type": "string", "minLength": 1 } }, "required": [ "queryName" ] }, "ExecuteAnalyticsQueryDto": { "type": "object", "properties": { "queryName": { "type": "string", "minLength": 1 }, "parameters": { "type": "object", "additionalProperties": {}, "selfRequired": false } }, "required": [ "queryName", "parameters" ] }, "ExecuteMultipleQueriesDto": { "type": "object", "properties": { "queries": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "parameters": { "type": "object", "additionalProperties": {} } }, "required": [ "name" ] } } }, "required": [ "queries" ] }, "ValidateParametersDto": { "type": "object", "properties": { "queryName": { "type": "string", "minLength": 1 }, "parameters": { "type": "object", "additionalProperties": {}, "selfRequired": true } }, "required": [ "queryName", "parameters" ] }, "CreateWebhookEndpointZodDto": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "url" ] }, "UpdateWebhookEndpointZodDto": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" } } }, "SetWebhookStatusDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "required": [ "status" ] }, "CreateWebhookEndpointDto": { "type": "object", "properties": { "url": { "type": "string", "description": "Webhook endpoint URL", "example": "https://example.com/webhook" }, "description": { "type": "string", "description": "Webhook endpoint description", "example": "Production webhook" } }, "required": [ "url" ] }, "UpdateWebhookEndpointDto": { "type": "object", "properties": { "url": { "type": "string", "description": "Webhook endpoint URL", "example": "https://example.com/webhook" }, "description": { "type": "string", "description": "Webhook endpoint description", "example": "Updated webhook" } } }, "UpdateThemePreferenceZodDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "light", "dark" ] } }, "required": [ "mode" ] }, "UpdateBrandThemeZodDto": { "type": "object", "properties": { "logo": { "type": "string" }, "brandName": { "type": "string", "minLength": 1 }, "primaryColor": { "type": "string", "minLength": 1 }, "fontFamily": { "type": "string" }, "fontSize": { "type": "string" }, "themes": { "type": "object", "properties": { "light": { "type": "object", "properties": { "background": { "type": "string" }, "surface": { "type": "string" }, "text": { "type": "string" }, "secondary": { "type": "string" } } }, "dark": { "type": "object", "properties": { "background": { "type": "string" }, "surface": { "type": "string" }, "text": { "type": "string" }, "secondary": { "type": "string" } } } }, "selfRequired": false } }, "required": [ "brandName", "primaryColor", "themes" ] }, "CreatePreregistrationZodDto": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "fullName": { "type": "string", "minLength": 2, "maxLength": 100 }, "companyName": { "type": "string", "minLength": 2, "maxLength": 100 }, "businessType": { "type": "string" }, "useCase": { "type": "string", "maxLength": 500 }, "customFields": { "type": "object", "additionalProperties": { "type": "string" }, "selfRequired": false } }, "required": [ "email", "fullName", "companyName", "customFields" ] }, "RevenueDataDto": { "type": "object", "properties": { "grossRevenue": { "type": "number" }, "refunds": { "type": "number" }, "platformFees": { "type": "number" }, "netRevenue": { "type": "number" }, "costOfRevenue": { "type": "number" }, "grossProfit": { "type": "object", "nullable": true }, "grossMargin": { "type": "object", "nullable": true }, "recognisedRevenue": { "type": "number" }, "deferredRevenue": { "type": "number" }, "hasCostTransactions": { "type": "boolean" } }, "required": [ "grossRevenue", "refunds", "platformFees", "netRevenue", "costOfRevenue", "recognisedRevenue", "deferredRevenue", "hasCostTransactions" ] }, "BalanceDataDto": { "type": "object", "properties": { "openingBalance": { "type": "number" }, "paymentsReceived": { "type": "number" }, "refundsIssued": { "type": "number" }, "platformFees": { "type": "number" }, "costsPaid": { "type": "number" }, "closingBalance": { "type": "number" }, "netChange": { "type": "number" } }, "required": [ "openingBalance", "paymentsReceived", "refundsIssued", "platformFees", "costsPaid", "closingBalance", "netChange" ] }, "MonthlyFinancialsDto": { "type": "object", "properties": { "month": { "type": "string" }, "revenue": { "$ref": "#/components/schemas/RevenueDataDto" }, "balance": { "$ref": "#/components/schemas/BalanceDataDto" } }, "required": [ "month", "revenue", "balance" ] }, "RevenueResponseDto": { "type": "object", "properties": { "current": { "$ref": "#/components/schemas/RevenueDataDto" }, "prior": { "$ref": "#/components/schemas/RevenueDataDto" }, "monthly": { "type": "array", "items": { "$ref": "#/components/schemas/MonthlyFinancialsDto" } }, "periodLabel": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code", "example": "SEK" } }, "required": [ "current", "prior", "monthly", "periodLabel", "currency" ] }, "BalanceResponseDto": { "type": "object", "properties": { "current": { "$ref": "#/components/schemas/BalanceDataDto" }, "monthly": { "type": "array", "items": { "$ref": "#/components/schemas/MonthlyFinancialsDto" } }, "periodLabel": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code", "example": "SEK" } }, "required": [ "current", "monthly", "periodLabel", "currency" ] }, "ProductRevenueRowDto": { "type": "object", "properties": { "productRef": { "type": "string" }, "productName": { "type": "string" }, "productType": { "type": "string" }, "revenue": { "type": "number" }, "costs": { "type": "number" }, "grossProfit": { "type": "object", "nullable": true }, "share": { "type": "number" }, "estimatedARR": { "type": "number" }, "transactionCount": { "type": "number" } }, "required": [ "productRef", "productName", "productType", "revenue", "costs", "share", "estimatedARR", "transactionCount" ] }, "TopProductDto": { "type": "object", "properties": { "name": { "type": "string" }, "revenue": { "type": "number" } }, "required": [ "name", "revenue" ] }, "RevenueByProductResponseDto": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductRevenueRowDto" } }, "activeProductCount": { "type": "number" }, "totalMRR": { "type": "number" }, "topProduct": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TopProductDto" } ] }, "currency": { "type": "string", "description": "ISO 4217 currency code", "example": "SEK" } }, "required": [ "products", "activeProductCount", "totalMRR", "currency" ] }, "LedgerEntryDto": { "type": "object", "properties": { "date": { "type": "string" }, "reference": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "direction": { "type": "string" }, "account": { "type": "string" }, "debit": { "type": "number" }, "credit": { "type": "number" }, "status": { "type": "string" } }, "required": [ "date", "reference", "description", "type", "direction", "account", "debit", "credit", "status" ] }, "LedgerResponseDto": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntryDto" } }, "total": { "type": "number" }, "totalCredit": { "type": "number" }, "totalDebit": { "type": "number" }, "currency": { "type": "string", "description": "ISO 4217 currency code", "example": "SEK" } }, "required": [ "entries", "total", "totalCredit", "totalDebit", "currency" ] }, "UpdateAccountStatusDto": { "type": "object", "properties": { "isActive": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "isActive" ] }, "HardDeleteAccountDto": { "type": "object", "properties": { "confirmationToken": { "type": "string", "minLength": 1 } }, "required": [ "confirmationToken" ] }, "StartImpersonationDto": { "type": "object", "properties": { "targetUserId": { "type": "string", "minLength": 1 } }, "required": [ "targetUserId" ] }, "UpdatePreregistrationStatusDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "contacted", "converted", "disqualified", "whitelisted" ] } }, "required": [ "status" ] } } } }