{ "components": { "schemas": { "ActivatePlanDto": { "properties": { "customerRef": { "maxLength": 20, "type": "string" }, "planRef": { "maxLength": 20, "type": "string" }, "productRef": { "maxLength": 20, "type": "string" } }, "required": [ "customerRef", "productRef", "planRef" ], "type": "object" }, "ActivatePlanResponseDto": { "properties": { "checkoutSessionId": { "type": "string" }, "checkoutUrl": { "type": "string" }, "creditBalance": { "type": "number" }, "creditsPerUnit": { "type": "number" }, "currency": { "type": "string" }, "message": { "type": "string" }, "purchaseRef": { "type": "string" }, "status": { "enum": [ "activated", "already_active", "topup_required", "payment_required", "invalid" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "AutoRechargeConfigDto": { "properties": { "enabled": { "description": "Whether auto-recharge is enabled", "example": true, "type": "boolean" }, "failureCount": { "description": "Consecutive failure count", "example": 0, "type": "number" }, "fundingSourceType": { "description": "Funding source type", "enum": [ "saved_card", "tokenized_card" ], "type": "string" }, "inFlightPaymentIntentId": { "description": "PaymentIntent ID of an in-flight recharge", "type": "string" }, "lastChargeAt": { "description": "Timestamp of the last successful charge", "type": "string" }, "lockAcquiredAt": { "description": "Timestamp the processing lock was acquired", "type": "string" }, "maxMonthlySpendMinor": { "description": "Optional monthly spend cap in topup.currency minor units", "example": 10000, "type": "number" }, "monthlySpendMinor": { "description": "Successful auto-recharge spend in the current UTC month", "example": 4500, "type": "number" }, "monthlySpendPeriod": { "description": "UTC YYYY-MM period key for monthlySpendMinor", "example": "2026-07", "type": "string" }, "paymentMethodId": { "description": "Saved payment method ID backing the recharge", "type": "string" }, "status": { "description": "Current config status", "enum": [ "active", "disabled", "failed", "pending_setup" ], "type": "string" }, "topup": { "$ref": "#/components/schemas/AutoRechargeTopupDto" }, "trigger": { "$ref": "#/components/schemas/AutoRechargeTriggerDto" }, "updatedAt": { "description": "Last update timestamp", "type": "string" } }, "required": [ "enabled", "trigger", "topup", "fundingSourceType", "status", "failureCount", "monthlySpendMinor", "updatedAt" ], "type": "object" }, "AutoRechargeDisplayDto": { "properties": { "currency": { "description": "Display currency code", "example": "USD", "type": "string" }, "exchangeRate": { "description": "Exchange rate used for display conversion", "example": 1, "type": "number" }, "formatted": { "$ref": "#/components/schemas/AutoRechargeDisplayFormattedDto" }, "rateSource": { "description": "Source of the exchange rate", "example": "live", "type": "string" }, "thresholdAmountMajor": { "description": "Threshold amount in display-currency major units", "example": 5, "type": "number" }, "topupAmountMajor": { "description": "Top-up amount in display-currency major units", "example": 20, "type": "number" } }, "required": [ "thresholdAmountMajor", "topupAmountMajor", "currency", "formatted", "exchangeRate", "rateSource" ], "type": "object" }, "AutoRechargeDisplayFormattedDto": { "properties": { "threshold": { "description": "Formatted threshold amount", "example": "$5.00", "type": "string" }, "topup": { "description": "Formatted top-up amount", "example": "$20.00", "type": "string" } }, "required": [ "threshold", "topup" ], "type": "object" }, "AutoRechargeGetResponse": { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/AutoRechargeConfigDto" } ], "description": "Current auto-recharge config, or null when not configured", "nullable": true }, "display": { "$ref": "#/components/schemas/AutoRechargeDisplayDto" } }, "type": "object" }, "AutoRechargeTopupDto": { "properties": { "amountMinor": { "description": "Top-up amount in currency minor units", "example": 2000, "type": "number" }, "currency": { "description": "ISO 4217 currency code", "example": "USD", "type": "string" }, "mode": { "description": "Top-up mode", "enum": [ "fixed" ], "example": "fixed", "type": "string" } }, "required": [ "mode", "amountMinor", "currency" ], "type": "object" }, "AutoRechargeTriggerDto": { "properties": { "thresholdAmountMinor": { "description": "Display-currency minor units for the balance threshold", "example": 500, "type": "number" }, "type": { "description": "Trigger kind", "enum": [ "balance" ], "example": "balance", "type": "string" } }, "required": [ "type", "thresholdAmountMinor" ], "type": "object" }, "AutoRechargeTriggeredResponse": { "properties": { "triggered": { "description": "Whether the server initiated an auto-recharge charge after this debit (TOPUP credit lands via webhook)", "example": true, "type": "boolean" } }, "required": [ "triggered" ], "type": "object" }, "BulkCreateUsageRequest": { "properties": { "events": { "items": { "properties": { "actionType": { "default": "api_call", "enum": [ "transaction", "api_call", "hour", "email", "storage", "custom" ], "type": "string" }, "customerRef": { "maxLength": 20, "minLength": 1, "type": "string" }, "description": { "type": "string" }, "duration": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "errorMessage": { "type": "string" }, "idempotencyKey": { "maxLength": 256, "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "outcome": { "default": "success", "enum": [ "success", "paywall", "fail" ], "type": "string" }, "productRef": { "maxLength": 20, "type": "string" }, "purchaseRef": { "maxLength": 20, "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" }, "BulkUsageResponse": { "properties": { "inserted": { "description": "Number of usage events inserted", "example": 2, "type": "number" }, "results": { "items": { "$ref": "#/components/schemas/BulkUsageResultResponse" }, "type": "array" }, "success": { "example": true, "type": "boolean" } }, "required": [ "success", "inserted", "results" ], "type": "object" }, "BulkUsageResultResponse": { "properties": { "creditDebit": { "oneOf": [ { "$ref": "#/components/schemas/CreditDebitSuccessResponse" }, { "$ref": "#/components/schemas/CreditDebitSkippedResponse" } ] }, "reference": { "example": "usage_A1B2C3D4", "type": "string" } }, "required": [ "reference" ], "type": "object" }, "BusinessDetailsDto": { "properties": { "businessName": { "description": "Legal business name", "type": "string" }, "country": { "description": "ISO 3166-1 alpha-2 country code", "type": "string" }, "customerRef": { "description": "Customer reference to persist business tax details on the customer record", "type": "string" }, "isBusiness": { "description": "Whether the purchase is on behalf of a business", "type": "boolean" }, "taxId": { "description": "Tax / VAT identification number", "type": "string" } }, "required": [ "isBusiness" ], "type": "object" }, "CancelPurchaseRequest": { "properties": { "reason": { "type": "string" } }, "type": "object" }, "CheckLimitRequest": { "properties": { "customerRef": { "maxLength": 20, "minLength": 1, "type": "string" }, "includeCheckoutSession": { "type": "boolean" }, "meterName": { "type": "string" }, "productRef": { "maxLength": 20, "minLength": 1, "type": "string" }, "usageType": { "type": "string" } }, "required": [ "customerRef", "productRef" ], "type": "object" }, "CloneProductDto": { "properties": { "name": { "minLength": 1, "pattern": "^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$", "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" }, "creditsPerUnit": { "type": "number" }, "currency": { "minLength": 1, "type": "string" }, "features": { "additionalProperties": true, "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" }, "pricingOptions": { "items": { "properties": { "basePrice": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "currency": { "maxLength": 3, "minLength": 3, "type": "string" }, "default": { "type": "boolean" }, "price": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "setupFee": { "exclusiveMinimum": false, "minimum": 0, "type": "number" } }, "required": [ "currency", "price" ], "type": "object" }, "type": "array" }, "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": { "maxLength": 20, "minLength": 1, "type": "string" }, "planRef": { "maxLength": 20, "type": "string" }, "productRef": { "maxLength": 20, "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": { "description": { "maxLength": 1000, "pattern": "^[\\p{L}\\p{N}\\s.,'\"&\\/()+:%;?!@#_[\\]\\-]*$", "type": "string" }, "email": { "format": "email", "type": "string" }, "externalRef": { "maxLength": 50, "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "name": { "maxLength": 100, "pattern": "^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$", "type": "string" }, "telephone": { "oneOf": [ { "pattern": "^\\+[1-9]\\d{6,14}$", "type": "string" }, { "enum": [ "" ], "type": "string" } ] } }, "required": [ "email", "metadata" ], "type": "object" }, "CreateCustomerSessionRequest": { "properties": { "customerRef": { "maxLength": 20, "minLength": 1, "type": "string" }, "productRef": { "maxLength": 20, "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" }, "autoRecharge": { "properties": { "currency": { "type": "string" }, "enabled": { "type": "boolean" }, "maxMonthlySpendMajor": { "exclusiveMaximum": false, "exclusiveMinimum": true, "maximum": 10000, "minimum": 0, "type": "number" }, "thresholdAmountMajor": { "exclusiveMaximum": false, "exclusiveMinimum": true, "maximum": 10000, "minimum": 0, "type": "number" }, "topupAmountMajor": { "exclusiveMaximum": false, "exclusiveMinimum": true, "maximum": 10000, "minimum": 0, "type": "number" }, "triggerType": { "enum": [ "balance" ], "type": "string" } }, "type": "object" }, "currency": { "type": "string" }, "customerRef": { "maxLength": 20, "minLength": 1, "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "planRef": { "maxLength": 20, "minLength": 1, "type": "string" }, "pricingTier": { "type": "string" }, "productRef": { "maxLength": 20, "minLength": 1, "type": "string" }, "purpose": { "default": "product", "enum": [ "product", "credit_topup", "usage_billing" ], "type": "string" } }, "required": [ "customerRef", "autoRecharge" ], "type": "object" }, "CreatePlanRequest": { "properties": { "accessExpiryDays": { "exclusiveMinimum": false, "minimum": 0, "type": "integer" }, "autoRenew": { "type": "boolean" }, "basePrice": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "billingCycle": { "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "type": "string" }, "billingModel": { "enum": [ "pre-paid", "post-paid" ], "type": "string" }, "billingStrategy": { "properties": { "type": { "type": "string" } }, "type": "object" }, "cancellationNoticeDays": { "exclusiveMinimum": false, "minimum": 0, "type": "integer" }, "creditsPerUnit": { "exclusiveMinimum": false, "minimum": 1, "type": "integer" }, "currency": { "type": "string" }, "default": { "type": "boolean" }, "description": { "maxLength": 500, "pattern": "^[\\p{L}\\p{N}\\s.,'\"&\\/()+:%;?!@#_[\\]\\-]*$", "type": "string" }, "features": { "additionalProperties": true, "type": "object" }, "freeUnits": { "exclusiveMinimum": false, "minimum": 0, "type": "integer" }, "fulfillment": { "properties": { "deliveryMethod": { "type": "string" }, "estimatedDelivery": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "hidden": { "type": "boolean" }, "limit": { "exclusiveMinimum": false, "minimum": 0, "type": "integer" }, "limits": { "additionalProperties": true, "type": "object" }, "maxActiveUsers": { "exclusiveMinimum": false, "minimum": 0, "type": "integer" }, "metadata": { "additionalProperties": true, "type": "object" }, "name": { "maxLength": 200, "minLength": 2, "pattern": "^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$", "type": "string" }, "overagePolicy": { "properties": { "allowOverage": { "type": "boolean" }, "maxOverage": { "type": "number" } }, "type": "object" }, "price": { "exclusiveMaximum": false, "exclusiveMinimum": false, "maximum": 10000000, "minimum": 0, "type": "number" }, "pricingOptions": { "items": { "properties": { "basePrice": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "currency": { "maxLength": 3, "minLength": 3, "type": "string" }, "default": { "type": "boolean" }, "price": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "setupFee": { "exclusiveMinimum": false, "minimum": 0, "type": "number" } }, "required": [ "currency", "price" ], "type": "object" }, "type": "array" }, "prorationPolicy": { "properties": { "enabled": { "type": "boolean" }, "method": { "enum": [ "proportional", "full", "none" ], "type": "string" } }, "type": "object" }, "returnPolicy": { "properties": { "allowed": { "type": "boolean" }, "conditions": { "type": "string" }, "period": { "type": "number" } }, "type": "object" }, "rolloverUnusedUnits": { "type": "boolean" }, "setupFee": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "status": { "enum": [ "active", "inactive", "archived" ], "type": "string" }, "taxBehavior": { "enum": [ "auto", "inclusive", "exclusive" ], "type": "string" }, "trialDays": { "exclusiveMinimum": false, "minimum": 0, "type": "integer" }, "type": { "enum": [ "recurring", "usage-based", "one-time", "hybrid" ], "type": "string" }, "usageTracking": { "properties": { "granularity": { "enum": [ "hourly", "daily", "weekly", "monthly" ], "type": "string" }, "method": { "enum": [ "automatic", "manual", "hybrid" ], "type": "string" } }, "type": "object" }, "warranty": { "properties": { "duration": { "type": "number" }, "terms": { "type": "string" }, "unit": { "type": "string" } }, "type": "object" } }, "required": [ "name", "usageTracking", "limits", "metadata", "features", "overagePolicy", "billingStrategy", "prorationPolicy", "returnPolicy", "fulfillment", "warranty" ], "type": "object" }, "CreateProductRequest": { "properties": { "config": { "properties": { "deliveryMethod": { "type": "string" }, "fulfillmentType": { "type": "string" }, "validityPeriod": { "exclusiveMinimum": true, "minimum": 0, "type": "integer" } }, "type": "object" }, "description": { "maxLength": 1000, "pattern": "^[\\p{L}\\p{N}\\s.,'\"&\\/()+:%;?!@#_[\\]\\-]*$", "type": "string" }, "imageUrl": { "type": "string" }, "isMcpPay": { "type": "boolean" }, "metadata": { "additionalProperties": true, "type": "object" }, "name": { "maxLength": 100, "minLength": 2, "pattern": "^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$", "type": "string" }, "productType": { "maxLength": 100, "type": "string" }, "taxBehavior": { "enum": [ "auto", "inclusive", "exclusive" ], "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": { "maxLength": 20, "minLength": 1, "type": "string" }, "description": { "type": "string" }, "duration": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "errorMessage": { "type": "string" }, "idempotencyKey": { "maxLength": 256, "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "outcome": { "default": "success", "enum": [ "success", "paywall", "fail" ], "type": "string" }, "productRef": { "maxLength": 20, "type": "string" }, "purchaseRef": { "maxLength": 20, "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" }, "CreditDebitSkippedResponse": { "properties": { "debited": { "enum": [ false ], "type": "number" }, "reason": { "description": "Reason no credit debit was recorded", "enum": [ "duplicate", "no_product_ref", "customer_not_found", "no_active_purchase", "plan_not_credit_based" ], "example": "duplicate", "type": "string" } }, "required": [ "debited", "reason" ], "type": "object" }, "CreditDebitSuccessResponse": { "properties": { "amount": { "description": "Credits debited for this usage event", "example": 10, "type": "number" }, "autoRecharge": { "$ref": "#/components/schemas/AutoRechargeTriggeredResponse" }, "debited": { "enum": [ true ], "type": "number" }, "unitsRemaining": { "description": "Estimated remaining units after debit", "example": 99, "type": "number" } }, "required": [ "debited", "amount", "unitsRemaining" ], "type": "object" }, "CustomerBalanceDisplayDto": { "properties": { "amountMajor": { "description": "Balance amount in the display currency major units (e.g. dollars)", "example": 42, "type": "number" }, "currency": { "description": "ISO 4217 display currency code", "example": "USD", "type": "string" }, "exchangeRate": { "description": "Exchange rate applied from USD to the display currency", "example": 1, "type": "number" }, "formatted": { "description": "Human-readable formatted balance", "example": "$42.00", "type": "string" }, "rateSource": { "description": "Source of the exchange rate used", "enum": [ "parity", "db", "fallback" ], "example": "parity", "type": "string" } }, "required": [ "amountMajor", "currency", "formatted", "exchangeRate", "rateSource" ], "type": "object" }, "CustomerBalanceResponse": { "properties": { "credits": { "description": "Raw credit balance in credits (mils)", "example": 4200, "type": "number" }, "creditsPerMinorUnit": { "description": "Number of credits per minor currency unit", "example": 100, "type": "number" }, "customerRef": { "description": "Customer reference identifier", "example": "cus_3c4d5e6f7g8h", "type": "string" }, "display": { "allOf": [ { "$ref": "#/components/schemas/CustomerBalanceDisplayDto" } ], "description": "Formatted balance display block for the display currency" }, "displayCurrency": { "description": "ISO 4217 display currency code", "example": "USD", "type": "string" }, "displayExchangeRate": { "description": "Exchange rate from USD to the display currency", "example": 1, "type": "number" } }, "required": [ "customerRef", "credits", "displayCurrency", "creditsPerMinorUnit", "displayExchangeRate", "display" ], "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" }, "DisableAutoRechargeResponse": { "properties": { "success": { "description": "Always true on success", "enum": [ true ], "example": true, "type": "number" } }, "required": [ "success" ], "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" }, "GrantCustomerCreditsRequest": { "properties": { "credits": { "exclusiveMinimum": true, "minimum": 0, "type": "integer" }, "reason": { "maxLength": 256, "pattern": "^[\\p{L}\\p{N}\\s.,'\"&\\/()+:%;?!@#_[\\]\\-]*$", "type": "string" } }, "required": [ "credits" ], "type": "object" }, "GrantCustomerCreditsResponse": { "properties": { "balance": { "description": "Customer credit balance after the grant", "type": "number" }, "credits": { "description": "Granted credit amount", "type": "number" }, "customerRef": { "description": "Customer reference identifier", "type": "string" }, "reason": { "description": "Machine-readable grant reason", "type": "string" }, "success": { "description": "Whether the grant was recorded", "type": "boolean" } }, "required": [ "success", "customerRef", "credits", "balance" ], "type": "object" }, "LimitBalanceDto": { "properties": { "creditBalance": { "description": "Credit balance in mils", "type": "number" }, "creditsPerUnit": { "description": "Credits per usage unit", "type": "number" }, "currency": { "type": "string" }, "remainingUnits": { "description": "Estimated whole units remaining from prepaid credit balance", "type": "number" } }, "required": [ "creditBalance", "creditsPerUnit", "currency" ], "type": "object" }, "LimitPlanItemDto": { "properties": { "billingCycle": { "type": "string" }, "billingModel": { "type": "string" }, "creditsPerUnit": { "description": "Credits per usage unit (usage-based plans)", "type": "number" }, "currency": { "type": "string" }, "freeUnits": { "type": "number" }, "name": { "type": "string" }, "price": { "description": "Price in smallest currency unit (e.g. cents)", "type": "number" }, "pricingOptions": { "description": "Per-currency price options for this plan", "items": { "$ref": "#/components/schemas/PlanPricingOptionDto" }, "type": "array" }, "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" }, "creditsPerUnit": { "description": "Credits per usage unit (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" }, "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": true, "type": "object" }, "name": { "type": "string" }, "originUrl": { "type": "string" }, "plans": { "items": { "properties": { "billingCycle": { "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "type": "string" }, "billingModel": { "enum": [ "pre-paid", "post-paid" ], "type": "string" }, "creditsPerUnit": { "type": "number" }, "currency": { "minLength": 1, "type": "string" }, "features": { "additionalProperties": true, "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" }, "pricingOptions": { "items": { "properties": { "basePrice": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "currency": { "maxLength": 3, "minLength": 3, "type": "string" }, "default": { "type": "boolean" }, "price": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "setupFee": { "exclusiveMinimum": false, "minimum": 0, "type": "number" } }, "required": [ "currency", "price" ], "type": "object" }, "type": "array" }, "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" }, "OneTimePurchaseInfo": { "properties": { "amount": { "description": "Amount in USD cents (normalised for aggregation)", "example": 9900, "type": "number" }, "completedAt": { "description": "When the one-time purchase was completed", "example": "2025-10-27T10:00:00Z", "type": "string" }, "currency": { "description": "ISO 4217 currency code of the customer-facing charge", "example": "USD", "type": "string" }, "productRef": { "description": "Product reference", "example": "prd_abc123", "type": "string" }, "reference": { "description": "Purchase reference", "example": "pur_1A2B3C4D", "type": "string" } }, "required": [ "reference", "amount", "currency", "completedAt" ], "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" }, "creditsPerUnit": { "description": "Credits per usage unit (integer, >= 1)", "example": 1, "type": "number" }, "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" }, "hidden": { "description": "Whether the plan is hidden from customer-facing surfaces. When true, the plan does not appear in checkout or the SDK catalog and can only be granted via direct assignment (enterprise plans).", "example": false, "type": "boolean" }, "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" }, "pricingOptions": { "description": "Per-currency price options for this plan", "items": { "$ref": "#/components/schemas/PlanPricingOptionDto" }, "type": "array" }, "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" }, "taxBehavior": { "description": "Tax inclusion behavior for business checkout", "enum": [ "auto", "inclusive", "exclusive" ], "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", "hybrid" ], "example": "recurring", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "type": "string" } }, "required": [ "type", "reference", "price", "currency", "requiresPayment", "hidden", "isActive", "status", "createdAt", "updatedAt" ], "type": "object" }, "PlanPricingOptionDto": { "properties": { "basePrice": { "description": "Base price in smallest currency unit (hybrid plans)", "example": 1999, "type": "number" }, "currency": { "description": "ISO 4217 currency code", "example": "USD", "type": "string" }, "default": { "description": "Whether this is the default currency option for the plan", "example": true, "type": "boolean" }, "price": { "description": "Price in smallest currency unit (e.g. cents)", "example": 2999, "type": "number" }, "setupFee": { "description": "One-time setup fee in smallest currency unit", "example": 500, "type": "number" } }, "required": [ "currency", "price" ], "type": "object" }, "ProcessPaymentCancelled": { "properties": { "status": { "enum": [ "cancelled" ], "example": "cancelled", "type": "string" } }, "required": [ "status" ], "type": "object" }, "ProcessPaymentFailed": { "properties": { "status": { "enum": [ "failed" ], "example": "failed", "type": "string" } }, "required": [ "status" ], "type": "object" }, "ProcessPaymentIntentDto": { "properties": { "customerRef": { "maxLength": 20, "minLength": 1, "type": "string" }, "planRef": { "maxLength": 20, "type": "string" }, "productRef": { "maxLength": 20, "minLength": 1, "type": "string" } }, "required": [ "customerRef" ], "type": "object" }, "ProcessPaymentProcessing": { "properties": { "status": { "enum": [ "processing" ], "example": "processing", "type": "string" } }, "required": [ "status" ], "type": "object" }, "ProcessPaymentSucceededBare": { "properties": { "status": { "enum": [ "succeeded" ], "example": "succeeded", "type": "string" } }, "required": [ "status" ], "type": "object" }, "ProcessPaymentSucceededOneTime": { "properties": { "oneTimePurchase": { "$ref": "#/components/schemas/OneTimePurchaseInfo" }, "status": { "enum": [ "succeeded" ], "example": "succeeded", "type": "string" }, "type": { "enum": [ "one-time" ], "example": "one-time", "type": "string" } }, "required": [ "status", "type", "oneTimePurchase" ], "type": "object" }, "ProcessPaymentSucceededRecurring": { "properties": { "purchase": { "$ref": "#/components/schemas/PurchaseInfo" }, "status": { "enum": [ "succeeded" ], "example": "succeeded", "type": "string" }, "type": { "enum": [ "recurring" ], "example": "recurring", "type": "string" } }, "required": [ "status", "type", "purchase" ], "type": "object" }, "ProcessPaymentTimeout": { "properties": { "message": { "description": "Detail message describing the timeout", "type": "string" }, "status": { "enum": [ "timeout" ], "example": "timeout", "type": "string" } }, "required": [ "status" ], "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" }, "PutAutoRechargeSdkDto": { "properties": { "currency": { "type": "string" }, "customerEmail": { "format": "email", "type": "string" }, "customerName": { "type": "string" }, "customerRef": { "minLength": 1, "type": "string" }, "deferSetupIntent": { "type": "boolean" }, "enabled": { "type": "boolean" }, "maxMonthlySpendMajor": { "exclusiveMaximum": false, "exclusiveMinimum": true, "maximum": 10000, "minimum": 0, "type": "number" }, "thresholdAmountMajor": { "exclusiveMaximum": false, "exclusiveMinimum": true, "maximum": 10000, "minimum": 0, "type": "number" }, "topupAmountMajor": { "exclusiveMaximum": false, "exclusiveMinimum": true, "maximum": 10000, "minimum": 0, "type": "number" }, "triggerType": { "enum": [ "balance" ], "type": "string" } }, "required": [ "enabled", "triggerType", "currency", "customerRef" ], "type": "object" }, "RecordBulkMeterEventsZodDto": { "properties": { "events": { "items": { "properties": { "customerRef": { "maxLength": 20, "minLength": 1, "type": "string" }, "meterName": { "minLength": 1, "type": "string" }, "productRef": { "maxLength": 20, "type": "string" }, "properties": { "additionalProperties": true, "type": "object" }, "timestamp": { "type": "string" }, "value": { "type": "number" } }, "required": [ "meterName", "customerRef" ], "type": "object" }, "minItems": 1, "type": "array" } }, "required": [ "events" ], "type": "object" }, "RecordMeterEventZodDto": { "properties": { "customerRef": { "maxLength": 20, "minLength": 1, "type": "string" }, "meterName": { "minLength": 1, "type": "string" }, "productRef": { "maxLength": 20, "type": "string" }, "properties": { "additionalProperties": true, "type": "object" }, "timestamp": { "type": "string" }, "value": { "type": "number" } }, "required": [ "meterName", "customerRef", "properties" ], "type": "object" }, "SaveAutoRechargeResponse": { "properties": { "config": { "$ref": "#/components/schemas/AutoRechargeConfigDto" }, "display": { "$ref": "#/components/schemas/AutoRechargeDisplayDto" }, "publishableKey": { "description": "Stripe publishable key for the resolved environment", "type": "string" }, "setupClientSecret": { "description": "Stripe SetupIntent client secret for card collection", "type": "string" }, "stripeAccountId": { "description": "Connected Stripe account ID", "type": "string" } }, "required": [ "config" ], "type": "object" }, "SdkMerchantResponseDto": { "properties": { "companyNumber": { "description": "Company registration number (EIN, Companies House No, Org No)", "example": "HRB12345", "type": "string" }, "country": { "description": "ISO-3166 alpha-2 country code of the merchant", "example": "US", "type": "string" }, "defaultCurrency": { "description": "ISO-4217 default settlement currency", "example": "usd", "type": "string" }, "displayName": { "description": "Brand name shown in UI", "example": "Acme", "type": "string" }, "iconUrl": { "description": "Absolute URL to the square app icon / logomark. Consumed by MCP host chromes, mobile avatar slots, and any surface where the landscape `logoUrl` would need letterboxing.", "example": "https://cdn.acme.com/icon.png", "type": "string" }, "legalName": { "description": "Legal entity name used in SCA mandate copy", "example": "Acme Inc.", "type": "string" }, "logoUrl": { "description": "Absolute URL to the merchant logo", "example": "https://cdn.acme.com/logo.png", "type": "string" }, "privacyUrl": { "example": "https://acme.com/privacy", "type": "string" }, "statementDescriptor": { "description": "Descriptor appearing on the customer card statement", "example": "ACME INC", "type": "string" }, "supportedTopupCurrencies": { "description": "Full set of currencies a customer may pay credit topups in, including the default currency. Omitted/single-entry means single-currency behavior.", "example": [ "USD", "EUR", "GBP" ], "items": { "type": "string" }, "type": "array" }, "supportEmail": { "example": "support@acme.com", "type": "string" }, "supportUrl": { "example": "https://acme.com/support", "type": "string" }, "taxId": { "description": "Tax identification number (US: EIN)", "example": "12-3456789", "type": "string" }, "termsUrl": { "example": "https://acme.com/terms", "type": "string" }, "vatNumber": { "description": "VAT identification number (UK/EU)", "example": "DE123456789", "type": "string" } }, "required": [ "displayName", "legalName" ], "type": "object" }, "SdkPaymentIntentListItem": { "properties": { "amount": { "description": "Amount in the charge currency (minor units)", "example": 4999, "type": "number" }, "clientSecret": { "description": "Client secret used to confirm the payment on the client", "example": "pi_1a2b3c4d5e6f7g8h_secret_xxx", "type": "string" }, "createdAt": { "description": "Creation timestamp", "example": "2025-10-11T10:30:00.000Z", "type": "string" }, "currency": { "description": "ISO 4217 currency code", "example": "usd", "type": "string" }, "planRef": { "description": "Plan reference", "example": "pln_2b3c4d5e6f7g", "type": "string" }, "processorPaymentId": { "description": "Payment processor payment intent ID", "example": "pi_1a2b3c4d5e6f7g8h", "type": "string" }, "status": { "description": "Payment intent status", "example": "succeeded", "type": "string" } }, "required": [ "processorPaymentId", "amount", "currency", "status" ], "type": "object" }, "SdkPaymentIntentListResponse": { "properties": { "paymentIntents": { "items": { "$ref": "#/components/schemas/SdkPaymentIntentListItem" }, "type": "array" }, "total": { "description": "Number of payment intents returned", "example": 1, "type": "number" } }, "required": [ "paymentIntents", "total" ], "type": "object" }, "SdkPaymentIntentResponse": { "properties": { "accountId": { "description": "Connected Stripe account ID (only present on create)", "example": "acct_1A2B3C4D", "type": "string" }, "amount": { "description": "Amount in the charge currency (minor units)", "example": 4999, "type": "number" }, "clientSecret": { "description": "Client secret used to confirm the payment on the client", "example": "pi_1a2b3c4d5e6f7g8h_secret_AbCdEf123456", "type": "string" }, "createdAt": { "description": "Creation timestamp", "example": "2025-10-18T10:30:00.000Z", "type": "string" }, "currency": { "description": "ISO 4217 currency code", "example": "usd", "type": "string" }, "customerRef": { "description": "Customer reference", "example": "cus_3c4d5e6f7g8h", "type": "string" }, "exchangeRate": { "description": "Exchange rate applied to the amount", "example": 1, "type": "number" }, "expiresAt": { "description": "Expiry timestamp of the payment intent", "example": "2025-10-19T10:30:00.000Z", "type": "string" }, "originalAmount": { "description": "Original amount in the payment currency (minor units)", "example": 4999, "type": "number" }, "planRef": { "description": "Plan reference", "example": "pln_2b3c4d5e6f7g", "type": "string" }, "processorPaymentId": { "description": "Payment processor payment intent ID", "example": "pi_1a2b3c4d5e6f7g8h", "type": "string" }, "publishableKey": { "description": "Stripe publishable key for the environment", "example": "pk_test_...", "type": "string" }, "status": { "description": "Payment intent status", "example": "requires_payment_method", "type": "string" }, "transactionId": { "description": "Ledger transaction ID", "example": "507f1f77bcf86cd799439011", "type": "string" } }, "required": [ "processorPaymentId", "amount", "currency", "status", "clientSecret", "publishableKey" ], "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" }, "creditsPerUnit": { "description": "Credits per usage unit (integer, >= 1)", "example": 1, "type": "number" }, "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" }, "hidden": { "description": "Whether the plan is hidden from the customer-facing catalog. Enterprise plans (true) do not appear in checkout or the SDK catalog and can only be granted via direct assignment.", "example": false, "type": "boolean" }, "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" }, "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", "hidden", "isActive", "status", "createdAt", "updatedAt" ], "type": "object" }, "SdkPlanSnapshotDto": { "properties": { "billingCycle": { "description": "Billing cycle", "example": "monthly", "nullable": true, "type": "string" }, "creditsPerUnit": { "description": "Credits per usage unit (integer, >= 1)", "example": 1, "type": "number" }, "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" }, "name": { "description": "Plan name captured at purchase time", "example": "Pro Monthly", "type": "string" }, "planType": { "description": "Plan type", "example": "recurring", "type": "string" }, "price": { "description": "Plan price in cents", "example": 2999, "type": "number" }, "reference": { "description": "Plan reference", "example": "pln_1A2B3C4D", "type": "string" } }, "required": [ "price", "currency", "planType" ], "type": "object" }, "SdkPlatformConfigResponseDto": { "properties": { "stripePublishableKey": { "description": "SolvaPay's platform Stripe publishable key for the authenticated provider's environment. Safe to expose browser-side; paired with the connected `accountId` returned from `create-payment-intent` for Stripe Connect direct charges. Omitted when not configured so callers can fall back cleanly to a hosted flow.", "example": "pk_test_...", "type": "string" } }, "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 the no-code MCP integration (SolvaPay reverse 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", "balance", "totalTransactions", "isMcpPay", "status", "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" }, "UpdateCustomerRequest": { "properties": { "description": { "maxLength": 1000, "pattern": "^[\\p{L}\\p{N}\\s.,'\"&\\/()+:%;?!@#_[\\]\\-]*$", "type": "string" }, "email": { "format": "email", "type": "string" }, "externalRef": { "maxLength": 50, "type": "string" }, "metadata": {}, "name": { "maxLength": 100, "pattern": "^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$", "type": "string" }, "telephone": { "oneOf": [ { "pattern": "^\\+[1-9]\\d{6,14}$", "type": "string" }, { "enum": [ "" ], "type": "string" } ] } }, "type": "object" }, "UpdatePlanRequest": { "properties": { "accessExpiryDays": { "exclusiveMinimum": false, "minimum": 0, "type": "integer" }, "autoRenew": { "type": "boolean" }, "billingCycle": { "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "type": "string" }, "billingModel": { "enum": [ "pre-paid", "post-paid" ], "type": "string" }, "billingStrategy": { "properties": { "type": { "type": "string" } }, "type": "object" }, "cancellationNoticeDays": { "exclusiveMinimum": false, "minimum": 0, "type": "integer" }, "creditsPerUnit": { "exclusiveMinimum": false, "minimum": 1, "type": "integer" }, "currency": { "type": "string" }, "default": { "type": "boolean" }, "description": { "maxLength": 500, "pattern": "^[\\p{L}\\p{N}\\s.,'\"&\\/()+:%;?!@#_[\\]\\-]*$", "type": "string" }, "features": { "additionalProperties": true, "type": "object" }, "freeUnits": { "exclusiveMinimum": false, "minimum": 0, "type": "integer" }, "fulfillment": { "properties": { "deliveryMethod": { "type": "string" }, "estimatedDelivery": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "hidden": { "type": "boolean" }, "limit": { "exclusiveMinimum": false, "minimum": 0, "type": "integer" }, "limits": { "additionalProperties": true, "type": "object" }, "maxActiveUsers": { "exclusiveMinimum": false, "minimum": 0, "type": "integer" }, "metadata": { "additionalProperties": true, "type": "object" }, "name": { "maxLength": 200, "minLength": 2, "pattern": "^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$", "type": "string" }, "overagePolicy": { "properties": { "allowOverage": { "type": "boolean" }, "maxOverage": { "type": "number" } }, "type": "object" }, "price": { "exclusiveMaximum": false, "exclusiveMinimum": false, "maximum": 10000000, "minimum": 0, "type": "number" }, "pricingOptions": { "items": { "properties": { "basePrice": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "currency": { "maxLength": 3, "minLength": 3, "type": "string" }, "default": { "type": "boolean" }, "price": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "setupFee": { "exclusiveMinimum": false, "minimum": 0, "type": "number" } }, "required": [ "currency", "price" ], "type": "object" }, "type": "array" }, "prorationPolicy": { "properties": { "enabled": { "type": "boolean" }, "method": { "enum": [ "proportional", "full", "none" ], "type": "string" } }, "type": "object" }, "returnPolicy": { "properties": { "allowed": { "type": "boolean" }, "conditions": { "type": "string" }, "period": { "type": "number" } }, "type": "object" }, "rolloverUnusedUnits": { "type": "boolean" }, "status": { "enum": [ "active", "inactive", "archived" ], "type": "string" }, "taxBehavior": { "enum": [ "auto", "inclusive", "exclusive" ], "type": "string" }, "warranty": { "properties": { "duration": { "type": "number" }, "terms": { "type": "string" }, "unit": { "type": "string" } }, "type": "object" } }, "required": [ "limits", "features", "metadata", "overagePolicy", "billingStrategy", "prorationPolicy", "returnPolicy", "fulfillment", "warranty" ], "type": "object" }, "UpdateProductRequest": { "properties": { "config": { "properties": { "deliveryMethod": { "type": "string" }, "fulfillmentType": { "type": "string" }, "validityPeriod": { "exclusiveMinimum": true, "minimum": 0, "type": "integer" } }, "type": "object" }, "description": { "maxLength": 1000, "pattern": "^[\\p{L}\\p{N}\\s.,'\"&\\/()+:%;?!@#_[\\]\\-]*$", "type": "string" }, "imageUrl": { "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "name": { "maxLength": 100, "minLength": 2, "pattern": "^[\\p{L}\\p{N} .,'\"&\\/()+:\\-]*$", "type": "string" }, "productType": { "maxLength": 100, "type": "string" }, "taxBehavior": { "enum": [ "auto", "inclusive", "exclusive" ], "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" }, "UsageRecordResponse": { "properties": { "creditDebit": { "oneOf": [ { "$ref": "#/components/schemas/CreditDebitSuccessResponse" }, { "$ref": "#/components/schemas/CreditDebitSkippedResponse" } ] }, "reference": { "example": "usage_A1B2C3D4", "type": "string" }, "success": { "example": true, "type": "boolean" } }, "required": [ "success", "reference" ], "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": { "maxLength": 20, "minLength": 1, "type": "string" }, "productRef": { "maxLength": 20, "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" }, "WebhookEventCategoryDto": { "properties": { "category": { "description": "Category key.", "example": "purchase", "type": "string" }, "description": { "description": "Category description.", "type": "string" }, "events": { "description": "Events in this category.", "items": { "$ref": "#/components/schemas/WebhookEventDefinitionDto" }, "type": "array" }, "label": { "description": "Human-readable category label.", "example": "Purchases & subscriptions", "type": "string" } }, "required": [ "category", "label", "description", "events" ], "type": "object" }, "WebhookEventDataDto": { "properties": { "object": { "additionalProperties": true, "description": "The resource that the event relates to.", "type": "object" }, "previous_attributes": { "additionalProperties": true, "description": "For *.updated events, the previous values of changed attributes.", "nullable": true, "type": "object" } }, "required": [ "object" ], "type": "object" }, "WebhookEventDefinitionDto": { "properties": { "description": { "description": "Human-readable description of the event.", "type": "string" }, "status": { "description": "Emission status.", "enum": [ "live", "planned" ], "example": "live", "type": "string" }, "type": { "$ref": "#/components/schemas/WebhookEventType", "example": "purchase.created" } }, "required": [ "type", "description", "status" ], "type": "object" }, "WebhookEventDto": { "properties": { "api_version": { "description": "API version that produced the event payload.", "example": "2024-01-01", "type": "string" }, "created": { "description": "Unix timestamp (seconds) when the event was created.", "example": 1717000000, "type": "number" }, "data": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventDataDto" } ], "description": "Event payload envelope." }, "id": { "description": "Unique event ID.", "example": "evt_1A2B3C4D", "type": "string" }, "livemode": { "description": "True for live-mode events, false for sandbox.", "example": true, "type": "boolean" }, "request": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventRequestDto" } ], "description": "Context about the triggering API request." }, "type": { "$ref": "#/components/schemas/WebhookEventType", "example": "purchase.created" } }, "required": [ "id", "type", "created", "api_version", "data", "livemode", "request" ], "type": "object" }, "WebhookEventRequestDto": { "properties": { "id": { "description": "ID of the API request that triggered the event.", "nullable": true, "type": "object" }, "idempotency_key": { "description": "Idempotency key of the triggering request.", "nullable": true, "type": "object" } }, "required": [ "id", "idempotency_key" ], "type": "object" }, "WebhookEventType": { "description": "Event type.", "enum": [ "customer.created", "customer.updated", "customer.deleted", "purchase.created", "purchase.activated", "purchase.updated", "purchase.trial_ending", "purchase.trial_converted", "purchase.suspended", "purchase.past_due", "purchase.cancellation_scheduled", "purchase.cancelled", "purchase.reactivated", "purchase.expired", "purchase.renewed", "purchase.renewal_reminder", "purchase.refunded", "purchase.plan_changed", "payment.succeeded", "payment.failed", "payment.refunded", "payment.refund_failed", "payment.refund_pending", "payment.canceled", "payment.disputed", "payment.dispute_closed", "payout.paid", "payout.failed", "checkout_session.created", "checkout_session.completed", "checkout_session.expired", "customer.credit.topped_up", "customer.credit.low_balance", "customer.credit.exhausted", "customer.credit.debited", "customer.credit.granted", "customer.credit.adjusted", "customer.credit.auto_topup_failed", "usage.charged", "usage.recorded", "usage.reset", "product.created", "product.updated", "product.archived", "plan.created", "plan.updated", "plan.archived" ], "type": "string" } }, "securitySchemes": { "api_key": { "description": "Provider secret API key supplied in the Authorization header.", "in": "header", "name": "Authorization", "type": "apiKey" }, "bearer": { "bearerFormat": "JWT", "description": "Dashboard session JWT issued after provider/operator login.", "scheme": "bearer", "type": "http" }, "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" }, "SecretKey": { "bearerFormat": "JWT", "description": "Provider secret API key (sk_live_… / sk_test_…) supplied as a Bearer token.", "scheme": "bearer", "type": "http" } } }, "info": { "contact": {}, "description": "The SolvaPay REST API specification", "title": "SolvaPay REST API", "version": "1.0" }, "openapi": "3.0.0", "paths": { "/v1/sdk/activate": { "post": { "description": "Activates a specific plan on a product for a customer. Usage-based (PAYG) plans are topup-first: a zero-balance customer receives `topup_required` and only activates after a successful top-up, while free plans activate immediately and paid recurring / hybrid plans return `payment_required`.", "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": "Plan activation result" } }, "security": [ { "SecretKey": [] } ], "summary": "Activate a plan for a customer", "tags": [ "Activation" ] } }, "/v1/sdk/auto-recharge": { "delete": { "description": "Disables auto-recharge for the given customer. Idempotent.", "operationId": "AutoRechargeSdkController_deleteAutoRecharge", "parameters": [ { "in": "query", "name": "customerRef", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableAutoRechargeResponse" } } }, "description": "Auto-recharge was disabled." }, "400": { "description": "customerRef query parameter is required" } }, "security": [ { "SecretKey": [] } ], "summary": "Disable auto-recharge for a customer", "tags": [ "Auto Recharge" ] }, "get": { "description": "Returns the stored auto-recharge configuration (and display block) for the given customer, or a null config when none is set.", "operationId": "AutoRechargeSdkController_getAutoRecharge", "parameters": [ { "in": "query", "name": "customerRef", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoRechargeGetResponse" } } }, "description": "Current auto-recharge config, if present." }, "400": { "description": "customerRef query parameter is required" } }, "security": [ { "SecretKey": [] } ], "summary": "Get auto-recharge config for a customer", "tags": [ "Auto Recharge" ] }, "put": { "description": "Persists the auto-recharge configuration for a customer. When no reusable card is on file, a Stripe SetupIntent client secret is returned so the caller can collect one.", "operationId": "AutoRechargeSdkController_putAutoRecharge", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutAutoRechargeSdkDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveAutoRechargeResponse" } } }, "description": "Saved auto-recharge config and optional SetupIntent details." }, "400": { "description": "customerRef is required, or customer email is required to configure auto-recharge" } }, "security": [ { "SecretKey": [] } ], "summary": "Set or update auto-recharge config for a customer", "tags": [ "Auto Recharge" ] } }, "/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": [ { "SecretKey": [] } ], "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" ] }, "patch": { "description": "Updates an existing customer identified by reference. Use this to backfill or change fields such as `externalRef`, `name`, or `email`. Only the fields supplied in the body are modified.", "operationId": "CustomerSdkController_updateCustomer", "parameters": [ { "description": "Customer reference identifier", "in": "path", "name": "reference", "required": true, "schema": { "example": "cus_3c4d5e6f7g8h", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "linkExternalRef": { "summary": "Backfill externalRef", "value": { "externalRef": "auth_user_12345" } }, "updateProfile": { "summary": "Update name and email", "value": { "email": "jane@example.com", "name": "Jane Doe" } } }, "schema": { "$ref": "#/components/schemas/UpdateCustomerRequest" } } }, "description": "Fields to update (all optional)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } }, "description": "Customer updated successfully" }, "400": { "description": "Invalid update payload" }, "404": { "description": "Customer not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Update a customer", "tags": [ "Customers" ] } }, "/v1/sdk/customers/{reference}/balance": { "get": { "description": "Returns the credit balance for a customer identified by reference.", "operationId": "CustomerSdkController_getCustomerBalance", "parameters": [ { "description": "Customer reference identifier", "in": "path", "name": "reference", "required": true, "schema": { "example": "cus_3c4d5e6f7g8h", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBalanceResponse" } } }, "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/{reference}/credits": { "post": { "description": "Adds credits to a customer balance. Use Idempotency-Key to make grants safe to retry.", "operationId": "CustomerSdkController_grantCredits", "parameters": [ { "description": "Customer reference identifier", "in": "path", "name": "reference", "required": true, "schema": { "example": "cus_3c4d5e6f7g8h", "type": "string" } }, { "description": "Provider-scoped idempotency key for safe grant retries", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantCustomerCreditsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantCustomerCreditsResponse" } } }, "description": "Credits granted successfully" }, "404": { "description": "Customer not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Grant credits to a customer", "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": [ { "SecretKey": [] } ], "summary": "Check usage limits for a customer and product", "tags": [ "Limits" ] } }, "/v1/sdk/merchant": { "get": { "description": "Returns the subset of provider data safe to render in a customer-facing checkout: display name, legal name, support contact, terms and privacy URLs, and logo. Used by SDK components like MandateText and CheckoutSummary.", "operationId": "getMerchant", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkMerchantResponseDto" } } }, "description": "Merchant identity" }, "404": { "description": "Provider not found in the requested environment. Body includes a `code` (`provider_not_found_in_environment`), the `requestedEnvironment`, and `providerExistsInSandbox` so the SDK / CLI can branch on the recovery path." } }, "security": [ { "SecretKey": [] } ], "summary": "Get merchant identity for the authenticated provider", "tags": [ "Merchant" ] } }, "/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" }, "404": { "description": "Customer not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Record a meter event", "tags": [ "Meter Events" ] } }, "/v1/sdk/meter-events/bulk": { "post": { "description": "Persists each event with recordUsage (same shape as single POST), after shared meter/customer checks.", "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" }, "404": { "description": "One or more customers not found" } }, "security": [ { "SecretKey": [] } ], "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": { "$ref": "#/components/schemas/SdkPaymentIntentListResponse" } } }, "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": { "$ref": "#/components/schemas/SdkPaymentIntentResponse" } } }, "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}/business-details": { "post": { "description": "Applies business or consumer tax location to a payment intent and returns the calculated tax breakdown.", "operationId": "PaymentIntentSdkController_attachBusinessDetails", "parameters": [ { "description": "Stripe payment intent ID (pi_…)", "in": "path", "name": "processorPaymentId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailsDto" } } }, "required": true }, "responses": { "200": { "description": "Business details applied and tax breakdown returned" }, "400": { "description": "Invalid request or business details" }, "404": { "description": "Payment intent not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Attach business tax details to 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. Returns the current status of the payment intent; on success, the response is enriched with the Purchase row created by the webhook handler.", "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": { "schema": { "discriminator": { "propertyName": "status" }, "oneOf": [ { "$ref": "#/components/schemas/ProcessPaymentSucceededRecurring" }, { "$ref": "#/components/schemas/ProcessPaymentSucceededOneTime" }, { "$ref": "#/components/schemas/ProcessPaymentSucceededBare" }, { "$ref": "#/components/schemas/ProcessPaymentProcessing" }, { "$ref": "#/components/schemas/ProcessPaymentTimeout" }, { "$ref": "#/components/schemas/ProcessPaymentFailed" }, { "$ref": "#/components/schemas/ProcessPaymentCancelled" } ] } } }, "description": "Payment intent status with optional purchase enrichment on success" }, "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": { "$ref": "#/components/schemas/SdkPaymentIntentResponse" } } }, "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/payment-method": { "get": { "description": "Returns the customer's default card for the authenticated provider. Sourced from stored payment-method records (no Stripe round-trip). Returns `{ kind: 'none' }` when no card is on file.", "operationId": "PaymentMethodSdkController_getPaymentMethod", "parameters": [ { "description": "Customer reference (e.g. `customer_...`).", "in": "query", "name": "customerRef", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "discriminator": { "propertyName": "kind" }, "oneOf": [ { "properties": { "brand": { "example": "visa", "type": "string" }, "expMonth": { "example": 12, "maximum": 12, "minimum": 1, "type": "integer" }, "expYear": { "example": 2030, "type": "integer" }, "kind": { "enum": [ "card" ], "type": "string" }, "last4": { "example": "4242", "type": "string" } }, "required": [ "kind", "brand", "last4", "expMonth", "expYear" ], "type": "object" }, { "properties": { "kind": { "enum": [ "none" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] } } }, "description": "The customer's default card, or `{ kind: 'none' }` when no card is on file." } }, "security": [ { "SecretKey": [] } ], "summary": "Get the default payment method for a customer", "tags": [ "Payment Methods" ] } }, "/v1/sdk/platform-config": { "get": { "description": "Returns browser-safe platform values resolved against the provider environment. Today: the SolvaPay platform Stripe publishable key. This endpoint is the canonical home for future platform-wide, environment-gated SDK config (API version hints, feature flags, public hosted URLs) — additions land here instead of bloating /sdk/merchant (strictly provider identity) or /sdk/payment-intents (runs too late for pre-intent UI decisions).", "operationId": "getPlatformConfig", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkPlatformConfigResponseDto" } } }, "description": "Platform config" } }, "security": [ { "SecretKey": [] } ], "summary": "Get environment-aware platform config for the authenticated provider", "tags": [ "Platform Config" ] } }, "/v1/sdk/products": { "get": { "description": "Retrieves a paginated list of products for the authenticated provider. Supports filtering by status, search term, and no-code MCP integration 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" ], "type": "string" } }, { "description": "Filter no-code MCP integration products", "in": "query", "name": "isMcpPay", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "limit": { "description": "Applied page size (clamped to 1-100)", "type": "number" }, "offset": { "description": "Applied pagination offset", "type": "number" }, "products": { "items": { "$ref": "#/components/schemas/SdkProductResponse" }, "type": "array" }, "total": { "description": "Total number of products matching the filters", "type": "number" } }, "type": "object" } } }, "description": "Products retrieved successfully" } }, "security": [ { "SecretKey": [] } ], "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": [ { "SecretKey": [] } ], "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": { "content": { "application/json": { "schema": { "properties": { "action": { "description": "Outcome of the delete: hard delete in sandbox, soft-delete or deactivation in live depending on existing purchases", "enum": [ "deleted", "deactivated", "soft_deleted" ], "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Product deleted or deactivated successfully" }, "404": { "description": "Product not found" } }, "security": [ { "SecretKey": [] } ], "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": [ { "SecretKey": [] } ], "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": [ { "SecretKey": [] } ], "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": [ { "SecretKey": [] } ], "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": [ { "SecretKey": [] } ], "summary": "Configure MCP plans on an MCP product", "tags": [ "Products" ] } }, "/v1/sdk/products/{productRef}/plans": { "get": { "description": "Retrieves the plans belonging to a product, paginated in-memory. Returns SDK-shaped plans with money serialized to wire units and unsupported plan types normalised to \"recurring\".", "operationId": "PlanSdkController_listPlans", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "example": "prd_1A2B3C4D", "type": "string" } }, { "description": "Max results (default 50)", "in": "query", "name": "limit", "required": false, "schema": { "type": "number" } }, { "description": "Pagination offset (default 0)", "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": { "description": "Creates a plan under the product. Unfinished pricing fields (setup fee, trial days, rollover, tiers, etc.) are stripped from SDK input, and unsupported plan types fall back to \"recurring\".", "operationId": "PlanSdkController_createPlan", "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/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": { "description": "Removes a plan from the product.", "operationId": "PlanSdkController_deletePlan", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "example": "prd_1A2B3C4D", "type": "string" } }, { "description": "Plan reference or ID", "in": "path", "name": "planRef", "required": true, "schema": { "example": "pln_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Plan deleted successfully" }, "404": { "description": "Plan or product not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Delete a plan from a product", "tags": [ "Plans" ] }, "get": { "description": "Retrieves a single plan by reference or ID within the given product.", "operationId": "PlanSdkController_getPlan", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "example": "prd_1A2B3C4D", "type": "string" } }, { "description": "Plan reference or ID", "in": "path", "name": "planRef", "required": true, "schema": { "example": "pln_1A2B3C4D", "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": { "description": "Updates a plan under the product. Unfinished pricing fields are stripped from SDK input, and unsupported plan types fall back to \"recurring\".", "operationId": "PlanSdkController_updatePlan", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "example": "prd_1A2B3C4D", "type": "string" } }, { "description": "Plan reference or ID", "in": "path", "name": "planRef", "required": true, "schema": { "example": "pln_1A2B3C4D", "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": [ { "SecretKey": [] } ], "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": { "maxLength": 20, "type": "string" } }, { "description": "Filter by customer reference", "in": "query", "name": "customerRef", "required": false, "schema": { "maxLength": 20, "type": "string" } }, { "description": "Include free recurring purchases and free auto-enrollments (default true)", "in": "query", "name": "includeFree", "required": false, "schema": { "default": true, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchases": { "items": { "$ref": "#/components/schemas/SdkPurchaseResponse" }, "type": "array" } } } } }, "description": "Purchases retrieved successfully" } }, "security": [ { "SecretKey": [] } ], "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": [ { "SecretKey": [] } ], "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": [ { "SecretKey": [] } ], "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": [ { "SecretKey": [] } ], "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" } }, { "description": "Include free auto-enrollments (default true for customer-scoped views)", "in": "query", "name": "includeFree", "required": false, "schema": { "type": "boolean" } } ], "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": [ { "SecretKey": [] } ], "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": [ { "SecretKey": [] } ], "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": { "$ref": "#/components/schemas/UsageRecordResponse" } } }, "description": "Usage recorded successfully" }, "400": { "description": "Validation failed" } }, "security": [ { "SecretKey": [] } ], "summary": "Record a usage event", "tags": [ "Usage" ] } }, "/v1/sdk/usages/bulk": { "post": { "description": "Same persistence rules as POST /sdk/usages for each item: validate batch first, then one insert per event.", "operationId": "UsageSdkController_recordBulkUsage", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreateUsageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUsageResponse" } } }, "description": "Bulk usage events processed" }, "400": { "description": "Validation failed" } }, "security": [ { "SecretKey": [] } ], "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": [ { "SecretKey": [] } ], "summary": "Get user info and purchase status", "tags": [ "User Info" ] } }, "/v1/sdk/webhooks/event-schema": { "get": { "description": "Returns a representative example of the signed webhook payload every endpoint receives. Useful when building and type-checking a webhook handler; the live `type` will be one of the values from `event-types`.", "operationId": "WebhookSdkController_getEventSchema", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventDto" } } }, "description": "" } }, "security": [ { "SecretKey": [] } ], "summary": "Get the webhook event envelope schema", "tags": [ "Webhooks" ] } }, "/v1/sdk/webhooks/event-types": { "get": { "description": "Returns the catalog of webhook event types you can subscribe to, grouped by category. Use these `type` values when configuring an endpoint’s `enabledEvents`.", "operationId": "WebhookSdkController_listEventTypes", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/WebhookEventCategoryDto" }, "type": "array" } } }, "description": "" } }, "security": [ { "SecretKey": [] } ], "summary": "List webhook event types", "tags": [ "Webhooks" ] } } }, "servers": [], "tags": [] }