{ "components": { "schemas": { "ActivatePlanDto": { "properties": { "customerRef": { "type": "string" }, "planRef": { "type": "string" }, "productRef": { "type": "string" } }, "required": [ "customerRef", "productRef", "planRef" ], "type": "object" }, "ActivatePlanResponseDto": { "properties": { "checkoutSessionId": { "type": "string" }, "checkoutUrl": { "type": "string" }, "creditBalance": { "type": "number" }, "currency": { "type": "string" }, "message": { "type": "string" }, "pricePerUnit": { "type": "number" }, "purchaseRef": { "type": "string" }, "status": { "enum": [ "activated", "already_active", "topup_required", "payment_required", "invalid" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "BulkCreateUsageRequest": { "properties": { "events": { "items": { "properties": { "actionType": { "default": "api_call", "enum": [ "transaction", "api_call", "hour", "email", "storage", "custom" ], "type": "string" }, "customerRef": { "minLength": 1, "type": "string" }, "description": { "type": "string" }, "duration": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "errorMessage": { "type": "string" }, "idempotencyKey": { "maxLength": 256, "type": "string" }, "metadata": { "additionalProperties": {}, "type": "object" }, "outcome": { "default": "success", "enum": [ "success", "paywall", "fail" ], "type": "string" }, "productRef": { "type": "string" }, "purchaseRef": { "type": "string" }, "timestamp": { "format": "date-time", "type": "string" }, "units": { "default": 1, "exclusiveMaximum": false, "exclusiveMinimum": false, "maximum": 100000, "minimum": 0, "type": "integer" } }, "required": [ "customerRef", "timestamp" ], "type": "object" }, "maxItems": 1000, "minItems": 1, "type": "array" } }, "required": [ "events" ], "type": "object" }, "CancelPurchaseRequest": { "properties": { "reason": { "type": "string" } }, "type": "object" }, "CheckLimitRequest": { "properties": { "customerRef": { "minLength": 1, "type": "string" }, "meterName": { "type": "string" }, "planRef": { "type": "string" }, "productRef": { "minLength": 1, "type": "string" }, "usageType": { "type": "string" } }, "required": [ "customerRef", "productRef" ], "type": "object" }, "CloneProductDto": { "properties": { "name": { "minLength": 1, "type": "string" } }, "type": "object" }, "ConfigureMcpPlansDto": { "properties": { "plans": { "items": { "properties": { "billingCycle": { "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "type": "string" }, "billingModel": { "enum": [ "pre-paid", "post-paid" ], "type": "string" }, "currency": { "minLength": 1, "type": "string" }, "features": { "additionalProperties": {}, "type": "object" }, "freeUnits": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "key": { "minLength": 1, "type": "string" }, "limit": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "name": { "minLength": 1, "type": "string" }, "price": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "pricePerUnit": { "type": "number" }, "type": { "enum": [ "recurring", "one-time", "usage-based" ], "type": "string" } }, "required": [ "key", "name", "price", "currency" ], "type": "object" }, "type": "array" }, "toolMapping": { "items": { "properties": { "name": { "minLength": 1, "type": "string" }, "planKeys": { "items": { "type": "string" }, "type": "array" } }, "required": [ "name", "planKeys" ], "type": "object" }, "type": "array" } }, "type": "object" }, "ConfigureMcpPlansResult": { "properties": { "mcpServer": { "additionalProperties": true, "description": "Updated MCP server identity", "type": "object" }, "planMap": { "additionalProperties": true, "description": "Resolved plan mapping by key (includes existing free plan)", "type": "object" }, "product": { "allOf": [ { "$ref": "#/components/schemas/SdkProductResponse" } ], "description": "Updated product" } }, "required": [ "product", "mcpServer", "planMap" ], "type": "object" }, "CreateCheckoutSessionRequest": { "properties": { "customerRef": { "minLength": 1, "type": "string" }, "planRef": { "type": "string" }, "productRef": { "minLength": 1, "type": "string" }, "purpose": { "enum": [ "credit_topup" ], "type": "string" }, "returnUrl": { "type": "string" } }, "required": [ "customerRef" ], "type": "object" }, "CreateCheckoutSessionResponse": { "properties": { "checkoutUrl": { "description": "Full checkout URL based on backend configuration (ready to redirect customer)", "example": "https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788", "type": "string" }, "sessionId": { "description": "Checkout session ID/token", "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" } }, "required": [ "sessionId", "checkoutUrl" ], "type": "object" }, "CreateCustomerRequest": { "properties": { "email": { "format": "email", "type": "string" }, "externalRef": { "type": "string" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "name": { "type": "string" }, "telephone": { "type": "string" } }, "required": [ "email", "metadata" ], "type": "object" }, "CreateCustomerSessionRequest": { "properties": { "customerRef": { "minLength": 1, "type": "string" }, "productRef": { "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" }, "CreatePaymentIntentDto": { "properties": { "amount": { "exclusiveMaximum": false, "exclusiveMinimum": false, "maximum": 10000000, "minimum": 100, "type": "integer" }, "currency": { "type": "string" }, "customerRef": { "minLength": 1, "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "planRef": { "minLength": 1, "type": "string" }, "pricingTier": { "type": "string" }, "productRef": { "minLength": 1, "type": "string" }, "purpose": { "default": "product", "enum": [ "product", "credit_topup", "usage_billing" ], "type": "string" } }, "required": [ "customerRef" ], "type": "object" }, "CreatePlanRequest": { "properties": { "accessExpiryDays": { "type": "number" }, "billingCycle": { "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "type": "string" }, "billingModel": { "enum": [ "pre-paid", "post-paid" ], "type": "string" }, "currency": { "type": "string" }, "default": { "type": "boolean" }, "description": { "type": "string" }, "features": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "freeUnits": { "type": "number" }, "limit": { "type": "number" }, "limits": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "maxActiveUsers": { "type": "number" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "name": { "minLength": 1, "type": "string" }, "price": { "type": "number" }, "pricePerUnit": { "type": "number" }, "status": { "enum": [ "active", "inactive", "archived" ], "type": "string" }, "type": { "enum": [ "recurring", "usage-based", "hybrid", "one-time" ], "type": "string" } }, "required": [ "limits", "metadata", "features" ], "type": "object" }, "CreateProductRequest": { "properties": { "config": { "properties": { "deliveryMethod": { "type": "string" }, "fulfillmentType": { "type": "string" }, "validityPeriod": { "type": "number" } }, "selfRequired": false, "type": "object" }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "isMcpPay": { "type": "boolean" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "name": { "minLength": 1, "type": "string" }, "productType": { "type": "string" } }, "required": [ "name", "config", "metadata" ], "type": "object" }, "CreateUsageRequest": { "properties": { "actionType": { "default": "api_call", "enum": [ "transaction", "api_call", "hour", "email", "storage", "custom" ], "type": "string" }, "customerRef": { "minLength": 1, "type": "string" }, "description": { "type": "string" }, "duration": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "errorMessage": { "type": "string" }, "idempotencyKey": { "maxLength": 256, "type": "string" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "outcome": { "default": "success", "enum": [ "success", "paywall", "fail" ], "type": "string" }, "productRef": { "type": "string" }, "purchaseRef": { "type": "string" }, "timestamp": { "format": "date-time", "type": "string" }, "units": { "default": 1, "exclusiveMaximum": false, "exclusiveMinimum": false, "maximum": 100000, "minimum": 0, "type": "integer" } }, "required": [ "customerRef", "metadata", "timestamp" ], "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" }, "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" }, "LimitBalanceDto": { "properties": { "creditBalance": { "description": "Credit balance in mils", "type": "number" }, "currency": { "type": "string" }, "pricePerUnit": { "description": "Price per usage unit in mils", "type": "number" }, "remainingUnits": { "description": "Estimated whole units remaining from prepaid balance at current pricePerUnit", "type": "number" } }, "required": [ "creditBalance", "pricePerUnit", "currency" ], "type": "object" }, "LimitPlanItemDto": { "properties": { "billingCycle": { "type": "string" }, "billingModel": { "type": "string" }, "currency": { "type": "string" }, "freeUnits": { "type": "number" }, "name": { "type": "string" }, "price": { "description": "Price in smallest currency unit (e.g. cents)", "type": "number" }, "pricePerUnit": { "description": "Price per usage unit in mils (usage-based plans)", "type": "number" }, "reference": { "type": "string" }, "requiresPayment": { "type": "boolean" }, "type": { "type": "string" } }, "required": [ "reference", "type", "price", "currency", "requiresPayment" ], "type": "object" }, "LimitProductBriefDto": { "properties": { "name": { "type": "string" }, "reference": { "type": "string" } }, "required": [ "reference" ], "type": "object" }, "LimitResponse": { "properties": { "activationRequired": { "description": "True when the customer must activate a priced default plan before usage is allowed", "type": "boolean" }, "balance": { "allOf": [ { "$ref": "#/components/schemas/LimitBalanceDto" } ], "description": "Prepaid usage balance context when the default plan is usage-based" }, "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" }, "confirmationUrl": { "description": "Customer portal confirmation URL when activation is required (fallback when not starting checkout)", "type": "string" }, "creditBalance": { "description": "Credit balance in mils (for pre-paid usage-based plans)", "type": "number" }, "currency": { "description": "ISO 4217 currency code for credit fields", "type": "string" }, "meterName": { "description": "The meter name to use when tracking usage events", "example": "requests", "type": "string" }, "plans": { "description": "Active plans on the product available for activation or checkout", "items": { "$ref": "#/components/schemas/LimitPlanItemDto" }, "type": "array" }, "pricePerUnit": { "description": "Price per usage unit in mils (for pre-paid usage-based plans)", "type": "number" }, "product": { "allOf": [ { "$ref": "#/components/schemas/LimitProductBriefDto" } ], "description": "Product the limit check applies to" }, "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" }, "McpBootstrapDto": { "properties": { "authApiKey": { "type": "string" }, "authHeaderName": { "type": "string" }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "mcpDomain": { "type": "string" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "name": { "type": "string" }, "originUrl": { "format": "uri", "minLength": 1, "type": "string" }, "plans": { "items": { "properties": { "billingCycle": { "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "type": "string" }, "billingModel": { "enum": [ "pre-paid", "post-paid" ], "type": "string" }, "currency": { "minLength": 1, "type": "string" }, "features": { "additionalProperties": {}, "type": "object" }, "freeUnits": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "key": { "minLength": 1, "type": "string" }, "limit": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "name": { "minLength": 1, "type": "string" }, "price": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "pricePerUnit": { "type": "number" }, "type": { "enum": [ "recurring", "one-time", "usage-based" ], "type": "string" } }, "required": [ "key", "name", "price", "currency" ], "type": "object" }, "type": "array" }, "productType": { "type": "string" }, "tools": { "items": { "properties": { "description": { "type": "string" }, "name": { "minLength": 1, "type": "string" }, "noPlan": { "type": "boolean" }, "planKeys": { "items": { "type": "string" }, "type": "array" } }, "required": [ "name" ], "type": "object" }, "type": "array" } }, "required": [ "originUrl", "metadata" ], "type": "object" }, "McpBootstrapResult": { "properties": { "autoMappedTools": { "description": "Auto-discovered tools used during bootstrap", "items": { "properties": { "description": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "mcpServer": { "additionalProperties": true, "description": "Created or updated MCP server identity", "example": { "defaultPlanRef": "pln_FREE123", "mcpProxyUrl": "https://acme-docs.mcp.solvapay.com/mcp", "reference": "mcp_ABC123", "subdomain": "acme-docs", "url": "https://origin.example.com/mcp" }, "type": "object" }, "planMap": { "additionalProperties": true, "description": "Resolved plan mapping by bootstrap key", "example": { "free": { "name": "Free", "reference": "pln_FREE123" } }, "type": "object" }, "product": { "allOf": [ { "$ref": "#/components/schemas/SdkProductResponse" } ], "description": "Created product" }, "toolsAutoMapped": { "description": "True when tools were auto-discovered from origin because the request omitted tools", "example": true, "type": "boolean" } }, "required": [ "product", "mcpServer", "planMap" ], "type": "object" }, "Plan": { "properties": { "accessExpiryDays": { "description": "Access expiry in days", "type": "number" }, "billingCycle": { "description": "Billing cycle", "example": "monthly", "type": "string" }, "billingModel": { "description": "Billing model", "enum": [ "pre-paid", "post-paid" ], "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 (derived from currency)", "example": "$", "type": "string" }, "description": { "description": "Plan description", "example": "Best for teams getting started", "type": "string" }, "features": { "additionalProperties": true, "description": "Plan features", "type": "object" }, "freeUnits": { "description": "Number of free units included", "example": 100, "type": "number" }, "isActive": { "description": "Whether the plan is active (derived from status)", "example": true, "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" }, "measures": { "description": "What the plan measures for usage tracking", "example": "requests", "type": "string" }, "meterRef": { "description": "Meter reference for usage-based plans", "example": "mtr_1A2B3C4D", "type": "string" }, "name": { "description": "Plan name", "example": "Starter", "type": "string" }, "price": { "description": "Plan price in cents", "example": 2999, "type": "number" }, "pricePerUnit": { "description": "Price per usage unit in cents (supports decimals, e.g. 0.1 = 1/10 cent)", "example": 0.1, "type": "number" }, "reference": { "description": "Plan reference", "example": "pln_1A2B3C4D", "type": "string" }, "requiresPayment": { "description": "Whether payment is required", "example": true, "type": "boolean" }, "rolloverUnusedUnits": { "description": "Whether unused units roll over to next period", "example": false, "type": "boolean" }, "setupFee": { "description": "One-time setup fee", "example": 500, "type": "number" }, "status": { "description": "Plan status", "example": "active", "type": "string" }, "trialDays": { "description": "Free trial period in days", "example": 14, "type": "number" }, "type": { "description": "Plan type exposed in SDK", "enum": [ "recurring", "one-time", "usage-based" ], "example": "recurring", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "type": "string" } }, "required": [ "type", "reference", "price", "currency", "requiresPayment", "isActive", "status", "createdAt", "updatedAt" ], "type": "object" }, "ProcessPaymentIntentDto": { "properties": { "customerRef": { "minLength": 1, "type": "string" }, "planRef": { "type": "string" }, "productRef": { "minLength": 1, "type": "string" } }, "required": [ "productRef", "customerRef" ], "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 in USD cents (normalised for aggregation)", "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": "ISO 4217 currency code of the customer-facing charge", "example": "GBP", "type": "string" }, "endDate": { "description": "End date of purchase", "example": "2025-11-27T10:00:00Z", "type": "string" }, "exchangeRate": { "description": "Exchange rate from original currency to USD", "example": 1.32, "type": "number" }, "originalAmount": { "description": "Original amount in the payment currency (minor units)", "example": 7500, "type": "number" }, "planRef": { "description": "Plan reference from the plan snapshot, for reliable plan matching", "example": "pln_abc123", "type": "string" }, "planSnapshot": { "description": "Snapshot of the plan at time of purchase", "type": "object" }, "productName": { "description": "Product name", "example": "API Gateway Manager", "type": "string" }, "productRef": { "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" }, "RecordBulkMeterEventsZodDto": { "properties": { "events": { "items": { "properties": { "customerRef": { "minLength": 1, "type": "string" }, "meterName": { "minLength": 1, "type": "string" }, "productRef": { "type": "string" }, "properties": { "additionalProperties": {}, "type": "object" }, "timestamp": { "type": "string" }, "value": { "type": "number" } }, "required": [ "meterName", "customerRef" ], "type": "object" }, "minItems": 1, "type": "array" } }, "required": [ "events" ], "type": "object" }, "RecordMeterEventZodDto": { "properties": { "customerRef": { "minLength": 1, "type": "string" }, "meterName": { "minLength": 1, "type": "string" }, "productRef": { "type": "string" }, "properties": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "timestamp": { "type": "string" }, "value": { "type": "number" } }, "required": [ "meterName", "customerRef", "properties" ], "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" }, "isActive": { "description": "Whether the plan is active", "example": true, "type": "boolean" }, "limit": { "description": "Usage limit for the meter", "example": 10000, "type": "number" }, "limits": { "additionalProperties": true, "description": "Usage limits", "type": "object" }, "measures": { "description": "What the plan measures for usage tracking", "example": "requests", "type": "string" }, "meterRef": { "description": "Meter reference for usage-based limits", "example": "mtr_1A2B3C4D", "type": "string" }, "price": { "description": "Plan price in cents", "example": 2999, "type": "number" }, "pricePerUnit": { "description": "Price per usage unit in cents (supports decimals, e.g. 0.1 = 1/10 cent)", "example": 0.1, "type": "number" }, "reference": { "description": "Plan reference", "example": "pln_1A2B3C4D", "type": "string" }, "requiresPayment": { "description": "Whether payment is required", "example": true, "type": "boolean" }, "rolloverUnusedUnits": { "description": "Whether unused units roll over to next period", "example": false, "type": "boolean" }, "setupFee": { "description": "One-time setup fee", "example": 500, "type": "number" }, "status": { "description": "Plan status", "example": "active", "type": "string" }, "trialDays": { "description": "Free trial period in days", "example": 14, "type": "number" }, "updatedAt": { "description": "Last update timestamp", "type": "string" } }, "required": [ "reference", "price", "currency", "requiresPayment", "isActive", "status", "createdAt", "updatedAt" ], "type": "object" }, "SdkPlanSnapshotDto": { "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" }, "meterRef": { "description": "Meter reference", "example": "mtr_1A2B3C4D", "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 (supports decimals, e.g. 0.1 = 1/10 cent)", "example": 0.1, "type": "number" }, "reference": { "description": "Plan reference", "example": "pln_1A2B3C4D", "type": "string" } }, "required": [ "price", "currency", "planType" ], "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" }, "imageUrl": { "description": "URL to the product image", "type": "string" }, "isMcpPay": { "description": "Whether this product uses MCP Pay proxy", "example": false, "type": "boolean" }, "mcp": { "additionalProperties": true, "description": "MCP linkage details for MCP-enabled products", "example": { "defaultPlanRef": "pln_FREE123", "mcpProxyUrl": "https://acme-docs.mcp.solvapay.com/mcp", "mcpServerRef": "mcp_ABC123", "mcpSubdomain": "acme-docs", "originUrl": "https://origin.example.com/mcp" }, "type": "object" }, "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": [ "reference", "name", "status", "balance", "totalTransactions", "isMcpPay", "createdAt", "updatedAt" ], "type": "object" }, "SdkPurchaseResponse": { "properties": { "amount": { "description": "Amount in USD cents (normalised for aggregation)", "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": "Original payment currency code", "example": "GBP", "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" }, "exchangeRate": { "description": "Exchange rate from original currency to USD", "example": 1.3082, "type": "number" }, "isRecurring": { "description": "Is recurring", "example": true, "type": "boolean" }, "metadata": { "additionalProperties": true, "description": "Arbitrary metadata attached to the purchase", "type": "object" }, "nextBillingDate": { "description": "Next billing date", "type": "string" }, "originalAmount": { "description": "Original amount in the payment currency (cents/pence)", "example": 10000, "type": "number" }, "paidAt": { "description": "Paid at timestamp", "type": "string" }, "planSnapshot": { "allOf": [ { "$ref": "#/components/schemas/SdkPlanSnapshotDto" } ], "description": "Plan snapshot at time of purchase (null for credit topups)" }, "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": [ "reference", "customerRef", "customerEmail", "productRef", "status", "amount", "currency", "startDate", "isRecurring", "createdAt" ], "type": "object" }, "UpdatePlanRequest": { "properties": { "accessExpiryDays": { "type": "number" }, "billingCycle": { "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "type": "string" }, "billingModel": { "enum": [ "pre-paid", "post-paid" ], "type": "string" }, "currency": { "type": "string" }, "default": { "type": "boolean" }, "description": { "type": "string" }, "features": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "freeUnits": { "type": "number" }, "limit": { "type": "number" }, "limits": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "maxActiveUsers": { "type": "number" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "name": { "minLength": 1, "type": "string" }, "price": { "type": "number" }, "pricePerUnit": { "type": "number" }, "status": { "enum": [ "active", "inactive", "archived" ], "type": "string" } }, "required": [ "limits", "features", "metadata" ], "type": "object" }, "UpdateProductRequest": { "properties": { "config": { "properties": { "deliveryMethod": { "type": "string" }, "fulfillmentType": { "type": "string" }, "validityPeriod": { "type": "number" } }, "selfRequired": false, "type": "object" }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "name": { "type": "string" }, "productType": { "type": "string" }, "status": { "enum": [ "active", "inactive", "suspended" ], "type": "string" } }, "required": [ "config", "metadata" ], "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": { "minLength": 1, "type": "string" }, "productRef": { "minLength": 1, "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": { "meterRef": { "description": "Meter reference", "example": "meter_ABC123", "nullable": true, "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" } }, "securitySchemes": { "OAuth2": { "flows": { "authorizationCode": { "authorizationUrl": "https://api.solvapay.com/v1/customer/auth/authorize", "scopes": { "email": "Email address", "openid": "OpenID Connect scope", "profile": "Profile information" }, "tokenUrl": "https://api.solvapay.com/v1/customer/auth/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/activate": { "post": { "operationId": "ActivateSdkController_activate", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivatePlanDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivatePlanResponseDto" } } }, "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Activation" ] } }, "/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": { "$ref": "#/components/schemas/CreateCheckoutSessionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionResponse" } } }, "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", "productRef": "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", "productRef": "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/{reference}/balance": { "get": { "description": "Returns the credit balance(s) for a customer identified by reference. Optionally filter by currency using the query parameter.", "operationId": "CustomerSdkController_getCustomerBalance", "parameters": [ { "description": "Customer reference identifier", "in": "path", "name": "reference", "required": true, "schema": { "example": "cus_3c4d5e6f7g8h", "type": "string" } }, { "description": "Filter by ISO 4217 currency code", "in": "query", "name": "currency", "required": false, "schema": { "example": "USD", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "balances": [ { "balance": 4200, "currency": "USD" } ], "customerRef": "cus_3c4d5e6f7g8h" } } } }, "description": "Customer balance 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 credit balance", "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", "productRef": "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": "MeterEventsSdkController_recordEvent", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordMeterEventZodDto" } } }, "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": "MeterEventsSdkController_recordBulkEvents", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordBulkMeterEventsZodDto" } } }, "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", "planRef": "pln_2b3c4d5e6f7g", "processorPaymentId": "pi_1a2b3c4d5e6f7g8h", "status": "succeeded" } ], "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. 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": { "$ref": "#/components/schemas/CreatePaymentIntentDto" } } }, "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", "customerRef": "cus_3c4d5e6f7g8h", "exchangeRate": 1, "expiresAt": "2025-10-19T10:30:00.000Z", "originalAmount": 4999, "planRef": "pln_2b3c4d5e6f7g", "processorPaymentId": "pi_1a2b3c4d5e6f7g8h", "publishableKey": "pk_test_...", "status": "requires_payment_method" } } } }, "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/{processorPaymentId}/process": { "post": { "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.", "operationId": "PaymentIntentSdkController_processPaymentIntent", "parameters": [ { "description": "Payment processor ID returned from createPaymentIntent", "in": "path", "name": "processorPaymentId", "required": true, "schema": { "example": "pi_1a2b3c4d5e6f7g8h", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessPaymentIntentDto" } } }, "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 payment 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 payment 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/payment-intents/{reference}": { "get": { "description": "Retrieves detailed information about a specific payment intent including amount, currency, and client secret.", "operationId": "PaymentIntentSdkController_getPaymentIntent", "parameters": [ { "description": "Payment intent reference or processor payment ID", "in": "path", "name": "reference", "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", "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. In live mode, soft-deletes (preserves data but hides from listings). If the product has purchases in live mode, deactivates 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" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneProductDto" } } }, "required": true }, "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}/mcp/plans": { "put": { "description": "Configures plans and optional tool-to-plan mappings for an MCP product.", "operationId": "ProductSdkController_configureMcpPlans", "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/ConfigureMcpPlansDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureMcpPlansResult" } } }, "description": "MCP plans configured successfully" }, "400": { "description": "Invalid MCP plans request or product is not MCP-enabled" }, "404": { "description": "Product not found" } }, "security": [ { "bearer": [] } ], "summary": "Configure MCP plans on an MCP 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/products/mcp/bootstrap": { "post": { "description": "Creates an MCP-enabled product with a unified plans array, configures origin URL, and maps tools to plans in one request.", "operationId": "ProductSdkController_bootstrapMcpProduct", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpBootstrapDto" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpBootstrapResult" } } }, "description": "MCP product bootstrapped successfully" }, "400": { "description": "Invalid bootstrap request" } }, "security": [ { "bearer": [] } ], "summary": "Bootstrap MCP product integration", "tags": [ "Products" ] } }, "/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 reference", "in": "query", "name": "productRef", "required": false, "schema": { "type": "string" } }, { "description": "Filter by customer reference", "in": "query", "name": "customerRef", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchases": { "items": { "$ref": "#/components/schemas/SdkPurchaseResponse" }, "type": "array" } } } } }, "description": "Purchases retrieved successfully" } }, "security": [ { "bearer": [] } ], "summary": "List purchases for provider", "tags": [ "Purchases" ] } }, "/v1/sdk/purchases/{purchaseRef}": { "get": { "description": "Retrieves a single purchase including plan snapshot, usage, and billing details.", "operationId": "PurchaseSdkController_getPurchase", "parameters": [ { "description": "Purchase reference or ID", "in": "path", "name": "purchaseRef", "required": true, "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkPurchaseResponse" } } }, "description": "Purchase retrieved successfully" }, "404": { "description": "Purchase not found" } }, "security": [ { "bearer": [] } ], "summary": "Get a purchase by 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/SdkPurchaseResponse" }, "success": { "type": "boolean" } } } } }, "description": "Purchase cancelled successfully" }, "404": { "description": "Purchase not found" } }, "security": [ { "bearer": [] } ], "summary": "Cancel a purchase", "tags": [ "Purchases" ] } }, "/v1/sdk/purchases/{purchaseRef}/reactivate": { "post": { "description": "Reactivates a purchase that was cancelled but has not yet reached its end date. Restores auto-renewal and clears cancellation fields.", "operationId": "PurchaseSdkController_reactivatePurchase", "parameters": [ { "description": "Purchase reference or ID", "in": "path", "name": "purchaseRef", "required": true, "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchase": { "$ref": "#/components/schemas/SdkPurchaseResponse" }, "success": { "type": "boolean" } } } } }, "description": "Purchase reactivated successfully" }, "400": { "description": "Purchase cannot be reactivated" }, "404": { "description": "Purchase not found" } }, "security": [ { "bearer": [] } ], "summary": "Reactivate a cancelled 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/SdkPurchaseResponse" }, "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/SdkPurchaseResponse" }, "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 into the Usage timeseries collection.", "operationId": "UsageSdkController_recordUsage", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUsageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "reference": { "example": "usage_A1B2C3D4", "type": "string" }, "success": { "example": true, "type": "boolean" } }, "type": "object" } } }, "description": "Usage recorded successfully" }, "400": { "description": "Validation failed" } }, "security": [ { "bearer": [] } ], "summary": "Record a usage event", "tags": [ "Usage" ] } }, "/v1/sdk/usages/bulk": { "post": { "description": "Records multiple usage events in a single request.", "operationId": "UsageSdkController_recordBulkUsage", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreateUsageRequest" } } }, "required": true }, "responses": { "200": { "description": "Bulk usage events processed" }, "400": { "description": "Validation failed" } }, "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": [] }