{ "components": { "schemas": { "AuthResponse": { "properties": {}, "type": "object" }, "CancelPurchaseRequest": { "properties": { "reason": { "description": "Reason for cancellation", "type": "string" } }, "type": "object" }, "CancelRenewalRequest": { "properties": { "reason": { "description": "Reason for cancelling renewal", "type": "string" } }, "type": "object" }, "CheckLimitRequest": { "properties": { "customerRef": { "description": "Customer reference identifier", "example": "cus_3C4D5E6F", "type": "string" }, "meterName": { "description": "Canonical usage meter name used for limit checks (for example: requests, tokens).", "example": "requests", "type": "string" }, "planRef": { "description": "Plan reference to pre-select when creating a checkout session. If provided and the customer needs to purchase, the checkout page skips plan selection and shows the payment form directly.", "example": "pln_2B3C4D5E", "type": "string" }, "productRef": { "description": "Product reference identifier", "example": "prd_1A2B3C4D", "type": "string" }, "usageType": { "description": "Usage type alias for meterName. If both are provided, meterName takes precedence.", "example": "requests", "type": "string" } }, "required": [ "customerRef", "productRef" ], "type": "object" }, "CheckoutSessionResponse": { "properties": { "amount": { "description": "Amount in cents", "example": 2999, "type": "number" }, "checkoutUrl": { "description": "Checkout URL to open the checkout page", "example": "https://solvapay.com/customer/checkout?id=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "type": "string" }, "currency": { "description": "Currency code", "example": "USD", "type": "string" }, "id": { "description": "Checkout session ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "sessionId": { "description": "Public session ID used in checkout URL", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "type": "string" }, "status": { "description": "Session status", "example": "active", "type": "string" } }, "required": [ "id", "sessionId", "amount", "currency", "status", "checkoutUrl" ], "type": "object" }, "CreateCheckoutSessionRequest": { "properties": { "customerReference": { "description": "Customer reference", "example": "cus_3c4d5e6f7g8h", "type": "string" }, "planRef": { "description": "Plan reference (optional)", "example": "pln_2b3c4d5e6f7g", "type": "string" }, "productRef": { "description": "Product reference (required)", "example": "prd_1a2b3c4d5e6f", "type": "string" } }, "required": [ "customerReference", "productRef" ], "type": "object" }, "CreateCustomerRequest": { "properties": { "email": { "description": "Customer email address (required)", "example": "customer@example.com", "type": "string" }, "externalRef": { "description": "External reference ID from your auth system to map this customer to an auth user (optional)", "example": "auth_user_12345", "type": "string" }, "name": { "description": "Customer full name (optional)", "example": "John Doe", "type": "string" } }, "required": [ "email" ], "type": "object" }, "CreateCustomerSessionRequest": { "properties": { "customerRef": { "description": "Customer reference identifier", "example": "cus_3c4d5e6f7g8h", "type": "string" }, "productRef": { "description": "Optional product reference or ID to scope the customer manage page to a single product.", "example": "prd_1a2b3c4d5e6f", "type": "string" } }, "required": [ "customerRef" ], "type": "object" }, "CreateCustomerSessionResponse": { "properties": { "customerUrl": { "description": "Full customer URL based on backend configuration (ready to redirect customer)", "example": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788", "type": "string" }, "sessionId": { "description": "Customer session ID/token", "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" } }, "required": [ "sessionId", "customerUrl" ], "type": "object" }, "CreateMeterDto": { "properties": { "aggregation": { "default": "count", "description": "Aggregation method for events", "enum": [ "count", "sum", "max", "min", "avg" ], "type": "string" }, "description": { "description": "Optional description", "example": "Tracks API call volume", "type": "string" }, "displayName": { "description": "Human-readable display name", "example": "Requests", "type": "string" }, "name": { "description": "Unique meter name (per provider)", "example": "requests", "type": "string" }, "unit": { "default": "requests", "description": "Unit label", "example": "requests", "type": "string" } }, "required": [ "name", "displayName" ], "type": "object" }, "CreatePlanRequest": { "properties": { "accessExpiryDays": { "description": "Access expiry in days", "example": 30, "type": "number" }, "billingCycle": { "description": "Billing cycle (required for recurring/hybrid, optional for post-paid usage-based)", "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "example": "monthly", "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "enum": [ "USD", "EUR", "GBP", "SEK", "NOK", "DKK", "CAD", "AUD", "JPY", "CHF", "PLN", "CZK", "HUF", "RON", "BGN", "HRK", "RSD", "MKD", "BAM", "ALL", "ISK", "TRY", "RUB", "UAH", "BYN", "MDL", "GEL", "AMD", "AZN", "KZT", "KGS", "TJS", "TMT", "UZS", "MNT", "CNY", "KRW", "THB", "VND", "IDR", "MYR", "SGD", "PHP", "INR", "PKR", "BDT", "LKR", "NPR", "AFN", "IRR", "IQD", "JOD", "KWD", "LBP", "OMR", "QAR", "SAR", "SYP", "AED", "YER", "ILS", "EGP", "MAD", "TND", "DZD", "LYD", "SDG", "ETB", "KES", "TZS", "UGX", "RWF", "BIF", "DJF", "SOS", "ERN", "SLL", "GMD", "GNF", "CVE", "STN", "AOA", "ZAR", "BWP", "SZL", "LSL", "NAD", "ZMW", "ZWL", "MZN", "MWK", "MGA", "MUR", "SCR", "KMF", "MVR" ], "example": "USD", "type": "string" }, "default": { "description": "Whether this is the default plan", "example": false, "type": "boolean" }, "features": { "additionalProperties": true, "description": "Plan features (generic key/value, shape is provider-defined)", "example": { "apiAccess": true, "prioritySupport": false }, "type": "object" }, "freeUnits": { "description": "Number of free units included", "example": 100, "type": "number" }, "isFreeTier": { "description": "Whether this is a free tier plan", "example": false, "type": "boolean" }, "limit": { "description": "Usage limit for the meter", "example": 10000, "type": "number" }, "limits": { "additionalProperties": true, "description": "Usage limits (shape varies by plan type)", "example": { "maxTransactions": 1000 }, "type": "object" }, "maxActiveUsers": { "description": "Maximum number of active users", "example": 10, "type": "number" }, "metadata": { "additionalProperties": true, "description": "Additional metadata", "type": "object" }, "meterId": { "description": "Meter ID (ObjectId) for free usage metering", "example": "507f1f77bcf86cd799439011", "type": "string" }, "price": { "description": "Plan price", "example": 29.99, "type": "number" }, "requiresPayment": { "description": "Whether payment is required", "example": true, "type": "boolean" }, "status": { "description": "Plan status", "enum": [ "active", "inactive", "archived" ], "example": "active", "type": "string" }, "type": { "description": "Plan type exposed in SDK", "enum": [ "recurring", "one-time" ], "example": "recurring", "type": "string" } }, "type": "object" }, "CreatePreregistrationDto": { "properties": { "businessType": { "example": "SaaS", "type": "string" }, "companyName": { "example": "Acme Corp", "type": "string" }, "customFields": { "additionalProperties": { "type": "string" }, "type": "object" }, "email": { "example": "jane@company.com", "type": "string" }, "fullName": { "example": "Jane Smith", "type": "string" }, "useCase": { "example": "Purchase billing for our platform", "maxLength": 500, "type": "string" } }, "required": [ "email", "fullName", "companyName" ], "type": "object" }, "CreateProductRequest": { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/ProductConfigDto" } ], "description": "Product-specific configuration" }, "description": { "description": "Product description", "example": "AI-powered writing tool", "type": "string" }, "imageUrl": { "description": "URL to the product image", "type": "string" }, "isMcpPay": { "default": false, "description": "Whether this product uses MCP Pay proxy", "type": "boolean" }, "metadata": { "additionalProperties": true, "description": "Arbitrary key-value metadata", "type": "object" }, "name": { "description": "Product name", "example": "AI Writing Assistant", "type": "string" }, "productType": { "description": "Free-form product type defined by the provider", "example": "Coding Assistant", "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreateSecretKey": { "properties": {}, "type": "object" }, "CreateUser": { "properties": {}, "type": "object" }, "CreateWebhookEndpointDto": { "properties": { "description": { "description": "Webhook endpoint description", "example": "Production webhook", "type": "string" }, "url": { "description": "Webhook endpoint URL", "example": "https://example.com/webhook", "type": "string" } }, "required": [ "url" ], "type": "object" }, "CustomerResponse": { "properties": { "email": { "description": "Customer email address", "example": "customer@example.com", "type": "string" }, "externalRef": { "description": "External reference ID from your auth system (if set during creation or update)", "example": "auth_user_12345", "type": "string" }, "name": { "description": "Customer full name", "example": "John Doe", "type": "string" }, "purchases": { "description": "Active purchases", "items": { "$ref": "#/components/schemas/PurchaseInfo" }, "type": "array" }, "reference": { "description": "Customer reference identifier", "example": "cus_3c4d5e6f7g8h", "type": "string" } }, "required": [ "reference", "name", "email" ], "type": "object" }, "CustomerSessionResponse": { "properties": { "customerUrl": { "description": "Customer URL to open the customer page", "example": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788", "type": "string" }, "id": { "description": "Customer session ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "sessionId": { "description": "Public session ID used in customer URL", "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" }, "status": { "description": "Session status", "example": "active", "type": "string" } }, "required": [ "id", "sessionId", "status", "customerUrl" ], "type": "object" }, "DynamicClientRegistrationDto": { "properties": { "client_name": { "example": "My AI Agent", "type": "string" }, "client_uri": { "example": "https://example.com", "type": "string" }, "grant_types": { "example": [ "authorization_code", "refresh_token" ], "items": { "type": "string" }, "type": "array" }, "logo_uri": { "example": "https://example.com/logo.png", "type": "string" }, "policy_uri": { "example": "https://example.com/policy", "type": "string" }, "redirect_uris": { "example": [ "https://agent.example.com/callback" ], "items": { "type": "string" }, "type": "array" }, "response_types": { "example": [ "code" ], "items": { "type": "string" }, "type": "array" }, "software_id": { "example": "agent-123", "type": "string" }, "software_version": { "example": "1.0.0", "type": "string" }, "tos_uri": { "example": "https://example.com/tos", "type": "string" } }, "required": [ "client_name", "redirect_uris" ], "type": "object" }, "DynamicClientRegistrationResponseDto": { "properties": { "client_id": { "example": "client-id-123", "type": "string" }, "client_id_issued_at": { "example": 1734567890, "type": "number" }, "client_name": { "example": "My AI Agent", "type": "string" }, "client_secret": { "example": "client-secret-456", "type": "string" }, "client_secret_expires_at": { "example": 0, "type": "number" }, "grant_types": { "example": [ "authorization_code", "refresh_token" ], "items": { "type": "string" }, "type": "array" }, "redirect_uris": { "example": [ "https://agent.example.com/callback" ], "items": { "type": "string" }, "type": "array" }, "response_types": { "example": [ "code" ], "items": { "type": "string" }, "type": "array" }, "scope": { "example": "openid profile email", "type": "string" }, "token_endpoint_auth_method": { "example": "client_secret_basic", "type": "string" } }, "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" ], "type": "object" }, "ExecuteAnalyticsQuery": { "properties": {}, "type": "object" }, "ExecuteMultipleQueries": { "properties": {}, "type": "object" }, "ExternalAccount": { "properties": { "accountHolderName": { "description": "Account holder name", "example": "John Doe", "type": "string" }, "accountHolderType": { "description": "Account holder type", "enum": [ "individual", "company" ], "example": "individual", "type": "string" }, "accountNumber": { "description": "Account number", "example": "000123456789", "type": "string" }, "country": { "description": "Country code", "example": "US", "type": "string" }, "currency": { "description": "Currency code", "example": "usd", "type": "string" }, "routingNumber": { "description": "Routing number", "example": "110000000", "type": "string" } }, "required": [ "country", "currency", "accountHolderName", "accountHolderType", "routingNumber", "accountNumber" ], "type": "object" }, "GetCustomerSessionResponse": { "properties": { "createdAt": { "description": "Session creation date", "example": "2025-01-01T11:45:00.000Z", "type": "string" }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerResponse" } ], "description": "Customer object from session data" }, "customerUrl": { "description": "Full customer URL based on backend configuration (ready to redirect customer)", "example": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788", "type": "string" }, "expiresAt": { "description": "Session expiration date", "example": "2025-01-01T12:00:00.000Z", "type": "string" }, "sessionId": { "description": "Customer session ID/token", "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" }, "status": { "description": "Session status", "enum": [ "active", "expired", "used" ], "example": "active", "type": "string" }, "updatedAt": { "description": "Session last update date", "example": "2025-01-01T11:45:00.000Z", "type": "string" } }, "required": [ "sessionId", "status", "customerUrl", "expiresAt", "customer", "createdAt", "updatedAt" ], "type": "object" }, "GithubLoginDto": { "properties": { "code": { "description": "The authorization code returned by GitHub", "type": "string" }, "redirect_uri": { "description": "The redirect URI used in the initial authorization request", "type": "string" }, "state": { "description": "The state parameter returned by GitHub (contains client_id)", "type": "string" } }, "required": [ "code", "redirect_uri", "state" ], "type": "object" }, "GoogleLoginDto": { "properties": { "code": { "description": "The authorization code returned by Google", "type": "string" }, "redirect_uri": { "description": "The redirect URI used in the initial authorization request", "type": "string" }, "state": { "description": "The state parameter returned by Google (contains client_id)", "type": "string" } }, "required": [ "code", "redirect_uri", "state" ], "type": "object" }, "LimitResponse": { "properties": { "checkoutSessionId": { "description": "Checkout session ID if payment is required", "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" }, "checkoutUrl": { "description": "Checkout URL if payment is required", "example": "https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788", "type": "string" }, "meterName": { "description": "The meter name to use when tracking usage events", "example": "requests", "type": "string" }, "remaining": { "description": "Remaining usage units before hitting the limit", "example": 997, "type": "number" }, "withinLimits": { "description": "Whether the customer is within their usage limits", "example": true, "type": "boolean" } }, "required": [ "withinLimits", "remaining" ], "type": "object" }, "Login": { "properties": { "email": { "description": "Email to send a 6-digit login code to", "type": "string" } }, "required": [ "email" ], "type": "object" }, "McpServerDto": { "properties": { "authHeaderName": { "description": "Custom auth header name for origin requests", "example": "X-API-Key", "type": "string" }, "avatarUrl": { "description": "Avatar image URL", "example": "https://example.com/avatar.png", "type": "string" }, "balance": { "description": "Current balance in cents", "example": 1500, "type": "number" }, "defaultPlanId": { "description": "Default plan ID for tool access gating", "example": "pln_default", "type": "string" }, "hasAuthApiKey": { "description": "Whether an auth API key is configured", "example": true, "type": "boolean" }, "id": { "description": "Server ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "mcpProxyUrl": { "description": "SolvaPay proxy URL that MCP clients connect to", "example": "https://mytelescope.mcp.solvapay.com/mcp", "type": "string" }, "name": { "description": "Domain slug used to derive the MCP endpoint subdomain", "example": "my-mcp-server", "type": "string" }, "productId": { "description": "Associated product ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "providerId": { "description": "Provider ID that owns this server", "example": "507f1f77bcf86cd799439011", "type": "string" }, "reference": { "description": "Unique server reference", "example": "mcp_abc123", "type": "string" }, "status": { "description": "Server status", "enum": [ "active", "inactive", "suspended" ], "example": "active", "type": "string" }, "subdomain": { "description": "URL-safe subdomain derived from name", "example": "my-mcp-server", "type": "string" }, "tools": { "description": "Registered tools for this server", "items": { "$ref": "#/components/schemas/McpToolDto" }, "type": "array" }, "totalTransactions": { "description": "Total number of tool-call transactions", "example": 42, "type": "number" }, "url": { "description": "Origin URL of the actual MCP server", "example": "https://origin.example.com/mcp", "type": "string" } }, "required": [ "name", "subdomain", "url", "providerId" ], "type": "object" }, "McpToolDto": { "properties": { "description": { "description": "Human-readable tool description", "example": "Search indexed documents", "type": "string" }, "isVirtual": { "description": "Whether this is a virtual platform tool handled by SolvaPay", "example": false, "type": "boolean" }, "name": { "description": "Tool name", "example": "search_documents", "type": "string" }, "noPlan": { "description": "If true, the tool is unprotected (no purchase check or usage tracking)", "example": false, "type": "boolean" }, "planIds": { "description": "Plan IDs that grant access to this tool", "example": [ "pln_abc123" ], "items": { "type": "string" }, "type": "array" } }, "required": [ "name" ], "type": "object" }, "Plan": { "properties": { "accessExpiryDays": { "description": "Access expiry in days", "type": "number" }, "billingCycle": { "description": "Billing cycle", "example": "monthly", "type": "string" }, "createdAt": { "description": "Creation timestamp", "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "example": "USD", "type": "string" }, "currencySymbol": { "description": "Currency symbol (derived from currency)", "example": "$", "type": "string" }, "features": { "additionalProperties": true, "description": "Plan features", "type": "object" }, "freeUnits": { "description": "Number of free units included", "example": 100, "type": "number" }, "id": { "description": "Plan ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "isActive": { "description": "Whether the plan is active (derived from status)", "example": true, "type": "boolean" }, "isFreeTier": { "description": "Whether this is a free tier plan", "example": false, "type": "boolean" }, "limit": { "description": "Usage limit for the meter", "example": 10000, "type": "number" }, "limits": { "additionalProperties": true, "description": "Usage limits", "type": "object" }, "maxActiveUsers": { "description": "Maximum number of active users", "type": "number" }, "meterId": { "description": "Meter ID (ObjectId)", "example": "507f1f77bcf86cd799439011", "type": "string" }, "price": { "description": "Plan price", "example": 29.99, "type": "number" }, "reference": { "description": "Plan reference", "example": "pln_1A2B3C4D", "type": "string" }, "requiresPayment": { "description": "Whether payment is required", "example": true, "type": "boolean" }, "status": { "description": "Plan status", "example": "active", "type": "string" }, "type": { "description": "Plan type exposed in SDK", "enum": [ "recurring", "one-time" ], "example": "recurring", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "type": "string" } }, "required": [ "type", "id", "reference", "price", "currency", "isFreeTier", "requiresPayment", "isActive", "status", "createdAt", "updatedAt" ], "type": "object" }, "PlanSnapshotDto": { "properties": { "billingCycle": { "description": "Billing cycle", "example": "monthly", "nullable": true, "type": "string" }, "currency": { "description": "Currency code", "example": "USD", "type": "string" }, "features": { "additionalProperties": true, "description": "Plan features", "nullable": true, "type": "object" }, "freeUnits": { "description": "Number of free units included", "example": 100, "type": "number" }, "limit": { "description": "Usage limit for the meter", "example": 5000, "type": "number" }, "limits": { "additionalProperties": true, "description": "Usage limits", "nullable": true, "type": "object" }, "meterId": { "description": "Meter ObjectId reference", "example": "507f1f77bcf86cd799439011", "type": "string" }, "planType": { "description": "Plan type", "example": "recurring", "type": "string" }, "price": { "description": "Plan price in cents", "example": 2999, "type": "number" }, "pricePerUnit": { "description": "Price per usage unit in cents", "example": 10, "type": "number" }, "reference": { "description": "Plan reference", "example": "pln_1A2B3C4D", "type": "string" } }, "required": [ "price", "currency", "planType" ], "type": "object" }, "ProductConfigDto": { "properties": { "deliveryMethod": { "description": "Delivery method", "example": "api", "type": "string" }, "fulfillmentType": { "description": "Fulfillment type", "example": "digital", "type": "string" }, "validityPeriod": { "description": "Validity period in days", "example": 30, "type": "number" } }, "type": "object" }, "PurchaseInfo": { "properties": { "amount": { "description": "Amount paid in original currency (in cents)", "example": 9900, "type": "number" }, "cancellationReason": { "description": "Reason for cancellation", "example": "Customer request", "type": "string" }, "cancelledAt": { "description": "When purchase was cancelled", "example": "2025-10-28T10:00:00Z", "type": "string" }, "currency": { "description": "Currency code", "example": "USD", "type": "string" }, "endDate": { "description": "End date of purchase", "example": "2025-11-27T10:00:00Z", "type": "string" }, "planSnapshot": { "description": "Snapshot of the plan at time of purchase", "type": "object" }, "productName": { "description": "Product name", "example": "API Gateway Manager", "type": "string" }, "productReference": { "description": "Product reference", "example": "prd_abc123", "type": "string" }, "reference": { "description": "Purchase reference", "example": "pur_1A2B3C4D", "type": "string" }, "startDate": { "description": "Start date", "example": "2025-10-27T10:00:00Z", "type": "string" }, "status": { "description": "Purchase status", "example": "active", "type": "string" } }, "required": [ "reference", "productName", "status", "startDate", "amount", "currency" ], "type": "object" }, "PurchaseResponse": { "properties": { "amount": { "description": "Amount in cents", "example": 9900, "type": "number" }, "autoRenew": { "description": "Auto-renew enabled", "type": "boolean" }, "billingCycle": { "description": "Billing cycle", "enum": [ "weekly", "monthly", "quarterly", "yearly" ], "type": "string" }, "cancellationReason": { "description": "Cancellation reason", "type": "string" }, "cancelledAt": { "description": "Cancelled at", "type": "string" }, "createdAt": { "description": "Created at", "type": "string" }, "currency": { "description": "Currency code", "example": "USD", "type": "string" }, "customerEmail": { "description": "Customer email", "example": "customer@example.com", "type": "string" }, "customerRef": { "description": "Customer reference", "example": "cus_3C4D5E6F", "type": "string" }, "endDate": { "description": "End date", "type": "string" }, "id": { "description": "Purchase ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "isFreeTier": { "description": "Whether this is a free tier purchase", "type": "boolean" }, "isRecurring": { "description": "Is recurring", "example": true, "type": "boolean" }, "nextBillingDate": { "description": "Next billing date", "type": "string" }, "paidAt": { "description": "Paid at timestamp", "type": "string" }, "planSnapshot": { "allOf": [ { "$ref": "#/components/schemas/PlanSnapshotDto" } ], "description": "Plan snapshot at time of purchase" }, "productId": { "description": "Product ID", "example": "507f1f77bcf86cd799439012", "type": "string" }, "productName": { "description": "Product name", "example": "API Gateway Manager", "type": "string" }, "productRef": { "description": "Product reference", "example": "prd_1A2B3C4D", "type": "string" }, "reference": { "description": "Purchase reference", "example": "pur_1A2B3C4D", "type": "string" }, "startDate": { "description": "Start date", "type": "string" }, "status": { "description": "Purchase status", "example": "active", "type": "string" }, "usage": { "allOf": [ { "$ref": "#/components/schemas/UsageBillingDto" } ], "description": "Usage billing state for usage-based plans" } }, "required": [ "id", "reference", "customerRef", "customerEmail", "productRef", "planSnapshot", "status", "amount", "currency", "startDate", "isRecurring", "createdAt" ], "type": "object" }, "RecordBulkMeterEventsDto": { "properties": { "events": { "description": "Array of events to record", "items": { "$ref": "#/components/schemas/RecordMeterEventDto" }, "type": "array" } }, "required": [ "events" ], "type": "object" }, "RecordMeterEventDto": { "properties": { "customerId": { "description": "Customer reference", "example": "cus_ABC123", "type": "string" }, "meterName": { "description": "Meter name to record against", "example": "requests", "type": "string" }, "properties": { "additionalProperties": true, "description": "Arbitrary key-value tags", "example": { "endpoint": "/api/v1/search", "region": "us-east-1" }, "type": "object" }, "timestamp": { "description": "ISO 8601 timestamp (defaults to now)", "type": "string" }, "value": { "default": 1, "description": "Numeric value (default 1)", "example": 1, "type": "number" } }, "required": [ "meterName", "customerId" ], "type": "object" }, "RequestEmailChange": { "properties": { "newEmail": { "type": "string" } }, "required": [ "newEmail" ], "type": "object" }, "SdkPlanResponse": { "properties": { "billingCycle": { "description": "Billing cycle", "example": "monthly", "type": "string" }, "billingModel": { "description": "Billing model", "example": "pre-paid", "type": "string" }, "createdAt": { "description": "Creation timestamp", "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "example": "USD", "type": "string" }, "currencySymbol": { "description": "Currency symbol", "example": "$", "type": "string" }, "features": { "additionalProperties": true, "description": "Plan features", "type": "object" }, "freeUnits": { "description": "Included free units", "example": 1000, "type": "number" }, "id": { "description": "Plan ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "isActive": { "description": "Whether the plan is active", "example": true, "type": "boolean" }, "isFreeTier": { "description": "Whether this is a free tier plan", "example": false, "type": "boolean" }, "limit": { "description": "Usage limit for the meter", "example": 10000, "type": "number" }, "limits": { "additionalProperties": true, "description": "Usage limits", "type": "object" }, "meterId": { "description": "Meter ID (ObjectId)", "example": "507f1f77bcf86cd799439011", "type": "string" }, "price": { "description": "Plan price", "example": 29.99, "type": "number" }, "pricePerUnit": { "description": "Price per unit", "example": 0.01, "type": "number" }, "reference": { "description": "Plan reference", "example": "pln_1A2B3C4D", "type": "string" }, "requiresPayment": { "description": "Whether payment is required", "example": true, "type": "boolean" }, "status": { "description": "Plan status", "example": "active", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "type": "string" } }, "required": [ "id", "reference", "price", "currency", "isFreeTier", "requiresPayment", "isActive", "status", "createdAt", "updatedAt" ], "type": "object" }, "SdkProductResponse": { "properties": { "balance": { "description": "Product balance in cents", "example": 0, "type": "number" }, "config": { "allOf": [ { "$ref": "#/components/schemas/ProductConfigDto" } ], "description": "Product-specific configuration" }, "createdAt": { "description": "Creation timestamp", "type": "string" }, "description": { "description": "Product description", "type": "string" }, "id": { "description": "Product ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "imageUrl": { "description": "URL to the product image", "type": "string" }, "isMcpPay": { "description": "Whether this product uses MCP Pay proxy", "example": false, "type": "boolean" }, "metadata": { "additionalProperties": true, "description": "Arbitrary key-value metadata", "type": "object" }, "name": { "description": "Product name", "example": "AI Writing Assistant", "type": "string" }, "plans": { "description": "Plans associated with this product", "items": { "$ref": "#/components/schemas/SdkPlanResponse" }, "type": "array" }, "productType": { "description": "Free-form product type", "type": "string" }, "reference": { "description": "Product reference", "example": "prd_1A2B3C4D", "type": "string" }, "status": { "description": "Product status", "example": "active", "type": "string" }, "totalTransactions": { "description": "Total number of transactions", "example": 0, "type": "number" }, "updatedAt": { "description": "Last update timestamp", "type": "string" } }, "required": [ "id", "reference", "name", "status", "balance", "totalTransactions", "isMcpPay", "createdAt", "updatedAt" ], "type": "object" }, "SelectCustomerSessionProductRequest": { "properties": { "productRef": { "description": "Product reference or ID to scope the customer manage session", "example": "prd_1a2b3c4d5e6f", "type": "string" } }, "required": [ "productRef" ], "type": "object" }, "Signup": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "type": { "enum": [ "provider", "admin", "super_admin" ], "type": "string" } }, "required": [ "name", "email" ], "type": "object" }, "ThemeModeColorsDto": { "properties": { "background": { "description": "Page background color", "example": "#f7f7f8", "type": "string" }, "secondary": { "description": "Secondary/muted text color", "example": "#5c5c5c", "type": "string" }, "surface": { "description": "Card/surface background color", "example": "#ffffff", "type": "string" }, "text": { "description": "Primary text color", "example": "#181818", "type": "string" } }, "type": "object" }, "ThemeOverridesDto": { "properties": { "dark": { "allOf": [ { "$ref": "#/components/schemas/ThemeModeColorsDto" } ], "description": "Dark mode color overrides" }, "light": { "allOf": [ { "$ref": "#/components/schemas/ThemeModeColorsDto" } ], "description": "Light mode color overrides" } }, "type": "object" }, "TosAcceptance": { "properties": { "ip": { "description": "IP address of user accepting ToS", "example": "192.168.1.1", "type": "string" } }, "required": [ "ip" ], "type": "object" }, "UpdateBrandThemeDto": { "properties": { "brandName": { "description": "Provider's brand name displayed on hosted pages", "example": "Acme Corp", "type": "string" }, "fontFamily": { "default": "Inter", "description": "Font family for hosted pages", "example": "Inter", "type": "string" }, "fontSize": { "default": "16px", "description": "Base font size", "example": "16px", "type": "string" }, "logo": { "description": "Logo image URL displayed in hosted page headers", "example": "/ui/files/download/provider-assets/provider-123/logos/logo.png", "type": "string" }, "primaryColor": { "description": "Primary/accent color in hex format", "example": "#3182ce", "type": "string" }, "themes": { "allOf": [ { "$ref": "#/components/schemas/ThemeOverridesDto" } ], "description": "Per-mode color overrides for light and dark themes" } }, "required": [ "brandName", "primaryColor" ], "type": "object" }, "UpdateConnectedAccount": { "properties": { "externalAccount": { "allOf": [ { "$ref": "#/components/schemas/ExternalAccount" } ], "description": "External bank account" }, "tosAcceptance": { "allOf": [ { "$ref": "#/components/schemas/TosAcceptance" } ], "description": "Terms of Service acceptance" }, "website": { "description": "Business website URL", "example": "https://example.com", "type": "string" } }, "type": "object" }, "UpdateMeterDto": { "properties": { "description": { "example": "Updated description", "type": "string" }, "displayName": { "example": "API Requests v2", "type": "string" }, "status": { "enum": [ "active", "archived" ], "type": "string" } }, "type": "object" }, "UpdatePlanRequest": { "properties": { "accessExpiryDays": { "description": "Access expiry in days", "example": 30, "type": "number" }, "billingCycle": { "description": "Billing cycle", "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "example": "monthly", "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "example": "USD", "type": "string" }, "default": { "description": "Whether this is the default plan", "example": false, "type": "boolean" }, "features": { "additionalProperties": true, "description": "Plan features (generic key/value, shape is provider-defined)", "example": { "apiAccess": true, "prioritySupport": false }, "type": "object" }, "freeUnits": { "description": "Number of free units included", "example": 100, "type": "number" }, "isFreeTier": { "description": "Whether this is a free tier plan", "example": false, "type": "boolean" }, "limit": { "description": "Usage limit for the meter", "example": 10000, "type": "number" }, "limits": { "additionalProperties": true, "description": "Usage limits (shape varies by plan type)", "example": { "maxTransactions": 1000 }, "type": "object" }, "maxActiveUsers": { "description": "Maximum number of active users", "example": 10, "type": "number" }, "metadata": { "additionalProperties": true, "description": "Additional metadata", "type": "object" }, "meterId": { "description": "Meter ID (ObjectId) for free usage metering", "example": "507f1f77bcf86cd799439011", "type": "string" }, "price": { "description": "Plan price", "example": 29.99, "type": "number" }, "requiresPayment": { "description": "Whether payment is required", "example": true, "type": "boolean" }, "status": { "description": "Plan status", "enum": [ "active", "inactive", "archived" ], "example": "active", "type": "string" } }, "type": "object" }, "UpdatePreferences": { "properties": {}, "type": "object" }, "UpdateProductRequest": { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/ProductConfigDto" } ], "description": "Product-specific configuration" }, "description": { "description": "Product description", "type": "string" }, "imageUrl": { "description": "URL to the product image", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Arbitrary key-value metadata", "type": "object" }, "name": { "description": "Product name", "type": "string" }, "productType": { "description": "Free-form product type defined by the provider", "type": "string" }, "status": { "description": "Product status", "enum": [ "active", "inactive", "suspended" ], "type": "string" } }, "type": "object" }, "UpdateProfile": { "properties": {}, "type": "object" }, "UpdateProviderDto": { "properties": { "businessEmail": { "description": "Business email address", "example": "business@example.com", "type": "string" }, "businessType": { "description": "Business type", "enum": [ "individual", "company" ], "example": "individual", "type": "string" }, "defaultCurrency": { "description": "Default currency code", "example": "usd", "type": "string" }, "description": { "description": "Provider description", "example": "My business", "type": "string" }, "legalEntity": { "description": "Legal entity information", "type": "object" }, "metadata": { "description": "Arbitrary metadata", "type": "object" }, "supportEmail": { "description": "Support email address", "example": "support@example.com", "type": "string" }, "supportTelephone": { "description": "Support telephone number", "example": "+1234567890", "type": "string" }, "telephone": { "description": "Business telephone number", "example": "+1234567890", "type": "string" }, "tosAcceptance": { "description": "Terms of Service acceptance", "type": "object" }, "website": { "description": "Business website URL", "example": "https://example.com", "type": "string" } }, "type": "object" }, "UpdateThemePreferenceDto": { "properties": { "mode": { "description": "Selected UI theme mode", "enum": [ "light", "dark" ], "example": "dark", "type": "string" } }, "required": [ "mode" ], "type": "object" }, "UpdateUser": { "properties": {}, "type": "object" }, "UpdateWebhookEndpointDto": { "properties": { "description": { "description": "Webhook endpoint description", "example": "Updated webhook", "type": "string" }, "url": { "description": "Webhook endpoint URL", "example": "https://example.com/webhook", "type": "string" } }, "type": "object" }, "UsageBillingDto": { "properties": { "overageCost": { "description": "Overage cost in cents", "example": 0, "type": "number" }, "overageUnits": { "description": "Units exceeding the plan limit", "example": 0, "type": "number" }, "periodEnd": { "description": "Period end date", "example": "2025-11-01T00:00:00Z", "type": "string" }, "periodStart": { "description": "Period start date", "example": "2025-10-01T00:00:00Z", "type": "string" }, "used": { "description": "Units consumed in current period", "example": 150, "type": "number" } }, "required": [ "used", "overageUnits", "overageCost" ], "type": "object" }, "UserInfoPlanDto": { "properties": { "billingCycle": { "example": "monthly", "nullable": true, "type": "string" }, "currency": { "example": "USD", "type": "string" }, "features": { "items": { "type": "string" }, "nullable": true, "type": "array" }, "limits": { "additionalProperties": true, "nullable": true, "type": "object" }, "price": { "description": "Price in minor currency units (e.g. cents)", "example": 2999, "type": "number" }, "reference": { "example": "pln_2B3C4D5E", "type": "string" }, "type": { "example": "recurring", "type": "string" } }, "required": [ "reference", "price", "currency", "type" ], "type": "object" }, "UserInfoPurchaseDto": { "properties": { "endDate": { "example": "2025-11-27T10:00:00Z", "nullable": true, "type": "string" }, "plan": { "$ref": "#/components/schemas/UserInfoPlanDto" }, "planType": { "example": "recurring", "type": "string" }, "productName": { "example": "My API Product", "type": "string" }, "reference": { "example": "pur_1A2B3C4D", "type": "string" }, "startDate": { "example": "2025-10-27T10:00:00Z", "nullable": true, "type": "string" }, "status": { "example": "active", "type": "string" }, "usage": { "$ref": "#/components/schemas/UserInfoUsageDto" } }, "required": [ "reference", "status", "productName", "planType" ], "type": "object" }, "UserInfoRequest": { "properties": { "customerRef": { "description": "Customer reference", "example": "cus_3C4D5E6F", "type": "string" }, "productRef": { "description": "Product reference", "example": "prd_1A2B3C4D", "type": "string" } }, "required": [ "customerRef", "productRef" ], "type": "object" }, "UserInfoResponse": { "properties": { "purchase": { "$ref": "#/components/schemas/UserInfoPurchaseDto" }, "status": { "description": "Human-readable status summary", "example": "Active subscription: My API Product (25% usage consumed)", "type": "string" }, "user": { "$ref": "#/components/schemas/UserInfoUserDto" }, "verifyUrl": { "description": "Customer portal session URL", "example": "https://solvapay.com/customer/manage?id=abc123", "nullable": true, "type": "string" } }, "required": [ "status" ], "type": "object" }, "UserInfoUsageDto": { "properties": { "meterId": { "description": "Meter ObjectId reference", "example": "507f1f77bcf86cd799439011", "type": "string" }, "percentUsed": { "example": 25, "nullable": true, "type": "number" }, "remaining": { "example": 750, "type": "number" }, "total": { "example": 1000, "type": "number" }, "used": { "example": 250, "type": "number" } }, "required": [ "total", "used", "remaining" ], "type": "object" }, "UserInfoUserDto": { "properties": { "email": { "example": "john@example.com", "type": "string" }, "externalRef": { "example": "auth_user_12345", "nullable": true, "type": "string" }, "name": { "example": "John Doe", "nullable": true, "type": "string" }, "reference": { "example": "cus_3C4D5E6F", "type": "string" } }, "required": [ "reference", "email" ], "type": "object" }, "VerifyEmail": { "properties": { "emailVerificationCode": { "type": "string" } }, "required": [ "emailVerificationCode" ], "type": "object" }, "VerifyEmailChange": { "properties": { "code": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "VerifyLoginCode": { "properties": { "code": { "description": "6-digit login code sent to email", "type": "string" }, "email": { "type": "string" } }, "required": [ "email", "code" ], "type": "object" } }, "securitySchemes": { "OAuth2": { "flows": { "authorizationCode": { "authorizationUrl": "https://api-dev.solvapay.com/v1/oauth/authorize", "scopes": { "email": "Email address", "openid": "OpenID Connect scope", "profile": "Profile information" }, "tokenUrl": "https://api-dev.solvapay.com/v1/oauth/token" } }, "type": "oauth2" } } }, "info": { "contact": {}, "description": "The SolvaPay REST API specification", "title": "SolvaPay REST API", "version": "1.0" }, "openapi": "3.0.0", "paths": { "/v1/sdk/checkout-sessions": { "post": { "description": "Creates a hosted checkout session for a customer to purchase a product plan. Returns a session ID and checkout URL for redirect.", "operationId": "CheckoutSessionSdkController_createCheckoutSession", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "customerRef": { "description": "Customer reference", "example": "cus_3C4D5E6F", "type": "string" }, "planRef": { "description": "Plan reference (optional — shows plan selector if omitted)", "example": "pln_2b3c4d5e", "type": "string" }, "productRef": { "description": "Product reference", "example": "prd_1A2B3C4D", "type": "string" }, "returnUrl": { "description": "URL to redirect after checkout", "type": "string" } }, "required": [ "customerRef", "productRef" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "checkoutUrl": { "description": "URL to redirect the customer to", "type": "string" }, "sessionId": { "description": "Checkout session ID", "type": "string" } }, "type": "object" } } }, "description": "Checkout session created" }, "400": { "description": "Missing customerRef or productRef" } }, "security": [ { "bearer": [] } ], "summary": "Create a checkout session", "tags": [ "Checkout Sessions" ] } }, "/v1/sdk/customers": { "get": { "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.", "operationId": "CustomerSdkController_getCustomerByQuery", "parameters": [ { "description": "Customer reference identifier (use exactly one query parameter)", "in": "query", "name": "reference", "required": false, "schema": { "example": "cus_3c4d5e6f7g8h", "type": "string" } }, { "description": "External reference ID from your auth system (use exactly one query parameter)", "in": "query", "name": "externalRef", "required": false, "schema": { "example": "auth_user_12345", "type": "string" } }, { "description": "Customer email address (use exactly one query parameter)", "in": "query", "name": "email", "required": false, "schema": { "example": "customer@example.com", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "email": "customer@example.com", "externalRef": "auth_user_12345", "name": "John Doe", "purchases": [ { "amount": 9900, "currency": "USD", "endDate": "2025-11-27T10:00:00Z", "productName": "API Gateway Manager", "productReference": "prd_abc123", "reference": "pur_1A2B3C4D", "startDate": "2025-10-27T10:00:00Z", "status": "active" } ], "reference": "cus_3c4d5e6f7g8h" }, "schema": { "$ref": "#/components/schemas/CustomerResponse" } } }, "description": "Customer retrieved successfully" }, "400": { "content": { "application/json": { "schema": { "example": { "error": "Bad Request", "message": "Must provide exactly one of reference, externalRef, or email", "statusCode": 400 } } } }, "description": "Invalid request - must provide exactly one of reference, externalRef, or email" }, "404": { "content": { "application/json": { "schema": { "example": { "error": "Not Found", "message": "Customer not found", "statusCode": 404 } } } }, "description": "Customer not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Get customer by reference, externalRef, or email", "tags": [ "Customers" ] }, "post": { "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.", "operationId": "CustomerSdkController_createCustomer", "parameters": [], "requestBody": { "content": { "application/json": { "examples": { "emailOnly": { "summary": "Email only", "value": { "email": "customer@example.com" } }, "withName": { "summary": "Customer with name", "value": { "email": "customer@example.com", "name": "John Doe" } } }, "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" } } }, "description": "Customer creation data", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "email": "customer@example.com", "externalRef": "auth_user_12345", "name": "John Doe", "reference": "cus_3c4d5e6f7g8h" }, "schema": { "$ref": "#/components/schemas/CustomerResponse" } } }, "description": "Customer created successfully" }, "400": { "content": { "application/json": { "schema": { "example": { "error": "Bad Request", "message": "Invalid email format", "statusCode": 400 } } } }, "description": "Invalid email or missing required fields" } }, "security": [ { "SecretKey": [] } ], "summary": "Create a new customer", "tags": [ "Customers" ] } }, "/v1/sdk/customers/{reference}": { "get": { "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.", "operationId": "CustomerSdkController_getCustomer", "parameters": [ { "description": "Customer reference identifier", "in": "path", "name": "reference", "required": true, "schema": { "example": "cus_3c4d5e6f7g8h", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "email": "customer@example.com", "externalRef": "auth_user_12345", "name": "John Doe", "purchases": [ { "amount": 9900, "currency": "USD", "endDate": "2025-11-27T10:00:00Z", "productName": "API Gateway Manager", "productReference": "prd_abc123", "reference": "pur_1A2B3C4D", "startDate": "2025-10-27T10:00:00Z", "status": "active" } ], "reference": "cus_3c4d5e6f7g8h" }, "schema": { "$ref": "#/components/schemas/CustomerResponse" } } }, "description": "Customer retrieved successfully" }, "404": { "content": { "application/json": { "schema": { "example": { "error": "Not Found", "message": "Customer with reference cus_3c4d5e6f7g8h not found", "statusCode": 404 } } } }, "description": "Customer not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Get customer by reference", "tags": [ "Customers" ] } }, "/v1/sdk/customers/customer-sessions": { "post": { "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.", "operationId": "CustomerSdkController_createCustomerSession", "parameters": [], "requestBody": { "content": { "application/json": { "examples": { "basic": { "summary": "Create customer session", "value": { "customerRef": "cus_3c4d5e6f7g8h" } } }, "schema": { "$ref": "#/components/schemas/CreateCustomerSessionRequest" } } }, "description": "Customer session creation request data", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "customerUrl": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788", "sessionId": "e3f1c2d4b6a89f001122334455667788" }, "schema": { "$ref": "#/components/schemas/CreateCustomerSessionResponse" } } }, "description": "Customer session created successfully" }, "400": { "content": { "application/json": { "schema": { "example": { "error": "Bad Request", "message": "Customer not found", "statusCode": 400 } } } }, "description": "Invalid request data or customer not found" }, "404": { "content": { "application/json": { "schema": { "example": { "error": "Not Found", "message": "Customer not found", "statusCode": 404 } } } }, "description": "Customer not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Create a customer session", "tags": [ "Customers" ] } }, "/v1/sdk/customers/customer-sessions/{sessionId}": { "get": { "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.", "operationId": "CustomerSdkController_getCustomerSession", "parameters": [ { "description": "Customer session ID/token", "in": "path", "name": "sessionId", "required": true, "schema": { "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2025-01-01T11:45:00.000Z", "customer": { "email": "customer@example.com", "externalRef": "auth_user_12345", "name": "John Doe", "purchases": [ { "amount": 9900, "currency": "USD", "endDate": "2025-11-27T10:00:00Z", "productName": "API Gateway Manager", "productReference": "prd_abc123", "reference": "pur_1A2B3C4D", "startDate": "2025-10-27T10:00:00Z", "status": "active" } ], "reference": "cus_3c4d5e6f7g8h" }, "customerUrl": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788", "expiresAt": "2025-01-01T12:00:00.000Z", "sessionId": "e3f1c2d4b6a89f001122334455667788", "status": "active", "updatedAt": "2025-01-01T11:45:00.000Z" }, "schema": { "$ref": "#/components/schemas/GetCustomerSessionResponse" } } }, "description": "Customer session retrieved successfully" }, "404": { "content": { "application/json": { "schema": { "example": { "error": "Not Found", "message": "Customer session not found: e3f1c2d4b6a89f001122334455667788", "statusCode": 404 } } } }, "description": "Customer session not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Get customer session by sessionId", "tags": [ "Customers" ] } }, "/v1/sdk/limits": { "post": { "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.", "operationId": "LimitsSdkController_checkLimits", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckLimitRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitResponse" } } }, "description": "Limit check result" }, "400": { "description": "Missing customerRef or productRef" }, "404": { "description": "Customer or product not found" } }, "security": [ { "bearer": [] } ], "summary": "Check usage limits for a customer and product", "tags": [ "Limits" ] } }, "/v1/sdk/meter-events": { "post": { "description": "Records a single usage event against a named meter.", "operationId": "MeterSdkController_recordEvent", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordMeterEventDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "example": true, "type": "boolean" } }, "type": "object" } } }, "description": "Event recorded" }, "400": { "description": "Invalid meter name or meter is archived" } }, "security": [ { "bearer": [] } ], "summary": "Record a meter event", "tags": [ "Meter Events" ] } }, "/v1/sdk/meter-events/bulk": { "post": { "description": "Records multiple usage events in a single request for high throughput.", "operationId": "MeterSdkController_recordBulkEvents", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordBulkMeterEventsDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "inserted": { "example": 50, "type": "number" }, "success": { "example": true, "type": "boolean" } }, "type": "object" } } }, "description": "Events recorded" }, "400": { "description": "Invalid meter name or meter is archived" } }, "security": [ { "bearer": [] } ], "summary": "Record meter events in bulk", "tags": [ "Meter Events" ] } }, "/v1/sdk/payment-intents": { "get": { "description": "Retrieves a paginated list of all payment intents created by the authenticated provider. Supports pagination through limit and offset query parameters.", "operationId": "PaymentIntentSdkController_getPaymentIntents", "parameters": [ { "description": "Maximum number of results", "in": "query", "name": "limit", "required": false, "schema": { "example": 50, "type": "number" } }, { "description": "Pagination offset", "in": "query", "name": "offset", "required": false, "schema": { "example": 0, "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "paymentIntents": [ { "amount": 4999, "clientSecret": "pi_1a2b3c4d5e6f7g8h_secret_xxx", "createdAt": "2025-10-11T10:30:00.000Z", "currency": "usd", "id": "pi_1a2b3c4d5e6f7g8h", "planRef": "pln_2b3c4d5e6f7g", "status": "succeeded", "stripePaymentIntentId": "pi_stripe_1234567890" } ], "total": 1 } } } }, "description": "Payment intents retrieved successfully" } }, "security": [ { "SecretKey": [] } ], "summary": "List payment intents for the provider", "tags": [ "Payment Intents" ] }, "post": { "description": "Creates a new payment intent for a customer to purchase a plan. Payment intents are used with Stripe.js to process payments. Requires an idempotency key to prevent duplicate charges. Returns client secret and publishable key needed for frontend integration.", "operationId": "PaymentIntentSdkController_createPaymentIntent", "parameters": [ { "description": "Unique idempotency key to prevent duplicate payments (required)", "in": "header", "name": "idempotency-key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "customerReference": { "description": "Customer reference identifier", "example": "cus_3c4d5e6f7g8h", "type": "string" }, "planRef": { "description": "Plan reference to purchase", "example": "pln_2b3c4d5e6f7g", "type": "string" }, "pricingTier": { "description": "Name of the pricing tier to purchase (for plans with pricingTiers). If not specified, uses the plan base price.", "example": "Pro", "type": "string" }, "productRef": { "description": "Product reference that owns the plan", "example": "prd_1A2B3C4D", "type": "string" } }, "required": [ "planRef", "productRef", "customerReference" ], "type": "object" } } }, "description": "Payment intent creation data", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "example": { "amount": 4999, "clientSecret": "pi_1a2b3c4d5e6f7g8h_secret_AbCdEf123456", "createdAt": "2025-10-18T10:30:00.000Z", "currency": "usd", "customerReference": "cus_3c4d5e6f7g8h", "exchangeRate": 1, "expiresAt": "2025-10-19T10:30:00.000Z", "id": "6743f1a2b3c4d5e6f7g8h9i0", "originalAmount": 4999, "planRef": "pln_2b3c4d5e6f7g", "publishableKey": "pk_test_...", "status": "requires_payment_method", "stripePaymentIntentId": "pi_1a2b3c4d5e6f7g8h", "transactionId": "6743f1a2b3c4d5e6f7g8h9i1" } } } }, "description": "Payment intent created successfully" }, "400": { "content": { "application/json": { "schema": { "example": { "error": "Bad Request", "message": "idempotency-key header is required", "statusCode": 400 } } } }, "description": "Missing required fields or invalid data" } }, "security": [ { "SecretKey": [] } ], "summary": "Create a payment intent", "tags": [ "Payment Intents" ] } }, "/v1/sdk/payment-intents/{id}": { "get": { "description": "Retrieves detailed information about a specific payment intent including amount, currency, and client secret for Stripe integration.", "operationId": "PaymentIntentSdkController_getPaymentIntent", "parameters": [ { "description": "Payment intent MongoDB ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "amount": 4999, "clientSecret": "pi_1a2b3c4d5e6f7g8h_secret_xxx", "currency": "usd", "planRef": "pln_2b3c4d5e6f7g" } } } }, "description": "Payment intent retrieved successfully" }, "404": { "content": { "application/json": { "schema": { "example": { "code": "PAYMENT_INTENT_NOT_FOUND", "error": "Payment intent not found", "success": false } } } }, "description": "Payment intent not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Get a specific payment intent by ID", "tags": [ "Payment Intents" ] } }, "/v1/sdk/payment-intents/{id}/process": { "post": { "description": "Processes a payment intent that has been confirmed on the client-side using Stripe.js. Polls the database for payment intent status to become succeeded (up to 10 seconds). Returns the current status of the payment intent.", "operationId": "PaymentIntentSdkController_processPaymentIntent", "parameters": [ { "description": "Stripe payment intent ID (format: pi_xxx)", "in": "path", "name": "id", "required": true, "schema": { "example": "pi_1a2b3c4d5e6f7g8h", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "customerRef": { "description": "Customer reference identifier", "example": "cus_456", "type": "string" }, "planRef": { "description": "Plan reference - helps determine if payment is for purchase", "example": "pln_789", "type": "string" }, "productRef": { "description": "Product reference that owns the plan", "example": "prd_123", "type": "string" } }, "required": [ "productRef", "customerRef" ], "type": "object" } } }, "description": "Payment processing data", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "cancelled": { "description": "Payment intent cancelled", "value": { "status": "cancelled" } }, "failed": { "description": "Payment intent failed", "value": { "status": "failed" } }, "succeeded": { "description": "Payment intent confirmed successfully", "value": { "status": "succeeded" } }, "timeout": { "description": "Timeout waiting for payment intent confirmation", "value": { "message": "Timeout while waiting for payment intent confirmation, try again later. This could be due to Stripe webhooks not being configured correctly.", "status": "timeout" } } }, "schema": { "properties": { "message": { "description": "Optional message, only present for timeout status", "example": "Timeout while waiting for payment intent confirmation, try again later. This could be due to Stripe webhooks not being configured correctly.", "type": "string" }, "status": { "description": "Payment intent status", "enum": [ "succeeded", "timeout", "failed", "cancelled" ], "example": "succeeded", "type": "string" } }, "type": "object" } } }, "description": "Payment intent status" }, "400": { "content": { "application/json": { "schema": { "example": { "error": "Bad Request", "message": "Payment not succeeded. Status: requires_payment_method", "statusCode": 400 } } } }, "description": "Payment not succeeded, invalid request, or forbidden" } }, "security": [ { "SecretKey": [] } ], "summary": "Process payment intent after client-side confirmation", "tags": [ "Payment Intents" ] } }, "/v1/sdk/products": { "get": { "description": "Retrieves a paginated list of products for the authenticated provider. Supports filtering by status, search term, and MCP Pay flag.", "operationId": "ProductSdkController_listProducts", "parameters": [ { "description": "Max results (1-100)", "in": "query", "name": "limit", "required": false, "schema": { "example": 50, "type": "number" } }, { "description": "Pagination offset", "in": "query", "name": "offset", "required": false, "schema": { "example": 0, "type": "number" } }, { "description": "Search by name or description", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } }, { "description": "Filter by status", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "inactive", "suspended" ], "type": "string" } }, { "description": "Filter MCP Pay products", "in": "query", "name": "isMcpPay", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Products retrieved successfully" } }, "security": [ { "bearer": [] } ], "summary": "List products", "tags": [ "Products" ] }, "post": { "description": "Creates a new product for the authenticated provider.", "operationId": "ProductSdkController_createProduct", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkProductResponse" } } }, "description": "Product created successfully" }, "400": { "description": "Missing required fields or validation error" } }, "security": [ { "bearer": [] } ], "summary": "Create a product", "tags": [ "Products" ] } }, "/v1/sdk/products/{productRef}": { "delete": { "description": "Deletes a product permanently in sandbox or when no purchases exist. In live mode with purchases, the product is deactivated instead.", "operationId": "ProductSdkController_deleteProduct", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "example": "prd_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "description": "Product deleted or deactivated successfully" }, "404": { "description": "Product not found" } }, "security": [ { "bearer": [] } ], "summary": "Delete a product", "tags": [ "Products" ] }, "get": { "description": "Retrieves a product by its reference or ID, including embedded plans.", "operationId": "ProductSdkController_getProduct", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "example": "prd_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkProductResponse" } } }, "description": "Product retrieved successfully" }, "404": { "description": "Product not found" } }, "security": [ { "bearer": [] } ], "summary": "Get a product by reference", "tags": [ "Products" ] }, "put": { "description": "Updates an existing product. Only provided fields are updated.", "operationId": "ProductSdkController_updateProduct", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "example": "prd_1A2B3C4D", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkProductResponse" } } }, "description": "Product updated successfully" }, "404": { "description": "Product not found" } }, "security": [ { "bearer": [] } ], "summary": "Update a product", "tags": [ "Products" ] } }, "/v1/sdk/products/{productRef}/clone": { "post": { "description": "Deep-copies a product including all its plans. Generates new references for the clone.", "operationId": "ProductSdkController_cloneProduct", "parameters": [ { "description": "Product reference or ID to clone", "in": "path", "name": "productRef", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkProductResponse" } } }, "description": "Product cloned successfully" }, "404": { "description": "Product not found" } }, "security": [ { "bearer": [] } ], "summary": "Clone a product", "tags": [ "Products" ] } }, "/v1/sdk/products/{productRef}/plans": { "get": { "operationId": "PlanSdkController_listPlans", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "limit": { "type": "number" }, "offset": { "type": "number" }, "plans": { "items": { "$ref": "#/components/schemas/Plan" }, "type": "array" }, "total": { "description": "Total number of plans for the product", "type": "number" } }, "type": "object" } } }, "description": "Plans retrieved successfully" }, "404": { "description": "Product not found" } }, "security": [ { "SecretKey": [] } ], "summary": "List plans for a product", "tags": [ "Plans" ] }, "post": { "operationId": "PlanSdkController_createPlan", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlanRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "Plan created successfully" }, "404": { "description": "Product not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Create a plan for a product", "tags": [ "Plans" ] } }, "/v1/sdk/products/{productRef}/plans/{planRef}": { "delete": { "operationId": "PlanSdkController_deletePlan", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "type": "string" } }, { "description": "Plan reference or ID", "in": "path", "name": "planRef", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plan deleted successfully" }, "404": { "description": "Plan or product not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Delete a plan from a product", "tags": [ "Plans" ] }, "get": { "operationId": "PlanSdkController_getPlan", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "type": "string" } }, { "description": "Plan reference or ID", "in": "path", "name": "planRef", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "Plan retrieved successfully" }, "404": { "description": "Plan or product not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Get a plan for a product", "tags": [ "Plans" ] }, "put": { "operationId": "PlanSdkController_updatePlan", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "type": "string" } }, { "description": "Plan reference or ID", "in": "path", "name": "planRef", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePlanRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "Plan updated successfully" }, "404": { "description": "Plan or product not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Update a plan for a product", "tags": [ "Plans" ] } }, "/v1/sdk/purchases": { "get": { "description": "Retrieves all purchases for the authenticated provider with optional filtering by status, product, or customer.", "operationId": "PurchaseSdkController_listPurchases", "parameters": [ { "description": "Filter by purchase status", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "active", "trialing", "past_due", "cancelled", "expired", "suspended", "refunded" ], "type": "string" } }, { "description": "Filter by product ID", "in": "query", "name": "productId", "required": false, "schema": { "type": "string" } }, { "description": "Filter by customer ID", "in": "query", "name": "customerId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchases": { "items": { "$ref": "#/components/schemas/PurchaseResponse" }, "type": "array" } } } } }, "description": "Purchases retrieved successfully" } }, "security": [ { "bearer": [] } ], "summary": "List purchases for provider", "tags": [ "Purchases" ] } }, "/v1/sdk/purchases/{id}": { "get": { "description": "Retrieves a single purchase including plan snapshot, usage, and billing details.", "operationId": "PurchaseSdkController_getPurchase", "parameters": [ { "description": "Purchase ID or reference", "in": "path", "name": "id", "required": true, "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseResponse" } } }, "description": "Purchase retrieved successfully" }, "404": { "description": "Purchase not found" } }, "security": [ { "bearer": [] } ], "summary": "Get a purchase by ID or reference", "tags": [ "Purchases" ] } }, "/v1/sdk/purchases/{purchaseRef}/cancel": { "post": { "description": "Cancels an active purchase. For recurring purchases, cancellation takes effect at the end of the current billing period.", "operationId": "PurchaseSdkController_cancelPurchase", "parameters": [ { "description": "Purchase reference or ID", "in": "path", "name": "purchaseRef", "required": true, "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPurchaseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchase": { "$ref": "#/components/schemas/PurchaseResponse" }, "success": { "type": "boolean" } } } } }, "description": "Purchase cancelled successfully" }, "404": { "description": "Purchase not found" } }, "security": [ { "bearer": [] } ], "summary": "Cancel a purchase", "tags": [ "Purchases" ] } }, "/v1/sdk/purchases/customer/{customerRef}": { "get": { "description": "Retrieves all purchases for a specific customer. Useful for billing history and access checks.", "operationId": "PurchaseSdkController_getPurchasesForCustomer", "parameters": [ { "description": "Customer reference or ID", "in": "path", "name": "customerRef", "required": true, "schema": { "example": "cus_3C4D5E6F", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchases": { "items": { "$ref": "#/components/schemas/PurchaseResponse" }, "type": "array" } } } } }, "description": "Customer purchases retrieved successfully" }, "404": { "description": "Customer not found" } }, "security": [ { "bearer": [] } ], "summary": "Get purchases for a customer", "tags": [ "Purchases" ] } }, "/v1/sdk/purchases/product/{productRef}": { "get": { "description": "Retrieves all purchases for a specific product. Each billing period creates a new purchase document.", "operationId": "PurchaseSdkController_getPurchasesForProduct", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "example": "prd_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchases": { "items": { "$ref": "#/components/schemas/PurchaseResponse" }, "type": "array" } } } } }, "description": "Product purchases retrieved successfully" }, "404": { "description": "Product not found" } }, "security": [ { "bearer": [] } ], "summary": "Get purchases for a product", "tags": [ "Purchases" ] } }, "/v1/sdk/usages": { "post": { "description": "Records a usage event against a named meter. Events are stored in a high-performance timeseries collection.", "operationId": "UsageSdkController_recordUsage", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "customerRef": { "description": "Customer reference (userId for the meter event)", "example": "cus_3C4D5E6F", "type": "string" }, "meterName": { "description": "Meter name to record against", "example": "requests", "type": "string" }, "properties": { "additionalProperties": true, "description": "Arbitrary event properties", "type": "object" }, "timestamp": { "description": "ISO 8601 timestamp (defaults to now)", "type": "string" }, "units": { "description": "Number of usage units (default: 1)", "example": 1, "type": "number" } }, "required": [ "customerRef", "meterName" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "example": true, "type": "boolean" }, "units": { "example": 1, "type": "number" } }, "type": "object" } } }, "description": "Usage recorded successfully" }, "400": { "description": "Missing customerRef or meterName" } }, "security": [ { "bearer": [] } ], "summary": "Record a usage event", "tags": [ "Usage" ] } }, "/v1/sdk/usages/bulk": { "post": { "description": "Records multiple meter events in a single request.", "operationId": "UsageSdkController_recordBulkUsage", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "events": { "items": { "properties": { "customerRef": { "type": "string" }, "meterName": { "type": "string" }, "properties": { "additionalProperties": true, "type": "object" }, "timestamp": { "type": "string" }, "units": { "type": "number" } }, "required": [ "customerRef", "meterName" ], "type": "object" }, "type": "array" } }, "required": [ "events" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Bulk usage events processed" }, "400": { "description": "Events array is required and must not be empty" } }, "security": [ { "bearer": [] } ], "summary": "Record bulk usage events", "tags": [ "Usage" ] } }, "/v1/sdk/user-info": { "post": { "description": "Returns customer profile, active purchase details including usage and plan info, and a customer portal URL.", "operationId": "UserInfoSdkController_getUserInfo", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfoRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfoResponse" } } }, "description": "User info with purchase status" }, "400": { "description": "Missing customerRef or productRef" }, "404": { "description": "Customer or product not found" } }, "security": [ { "bearer": [] } ], "summary": "Get user info and purchase status", "tags": [ "User Info" ] } } }, "servers": [], "tags": [] }