{ "openapi": "3.1.0", "info": { "title": "Decision Engine", "description": "Open-source payment gateway routing service by Juspay. Selects the optimal payment processor for each transaction in real-time using success-rate scoring, rule-based routing, and elimination logic.\n\n## Authentication\n\nThis API supports two authentication methods:\n\n1. **JWT Bearer Token** - For dashboard/user sessions\n - Header: `Authorization: Bearer `\n - Obtain via `/auth/login` endpoint\n\n2. **API Key** - For service-to-service/programmatic access\n - Header: `x-api-key: DE_<64_char_hex>`\n - Create via `/api-key/create` endpoint\n\nProtected endpoints require one of these authentication methods.", "version": "1.4.0", "contact": { "name": "Juspay", "url": "https://github.com/juspay/decision-engine" }, "license": { "name": "AGPL-3.0", "url": "https://www.gnu.org/licenses/agpl-3.0.html" } }, "servers": [ { "url": "http://localhost:8080", "description": "Local development" }, { "url": "https://sandbox.hyperswitch.io", "description": "Hyperswitch sandbox with x-feature: decision-engine" } ], "tags": [ { "name": "Health", "description": "Service liveness, readiness, and diagnostics" }, { "name": "Auth", "description": "Dashboard auth and merchant selection" }, { "name": "API Keys", "description": "Service-to-service API key management" }, { "name": "Gateway Decision", "description": "Core routing decision APIs" }, { "name": "Score Feedback", "description": "Feed transaction outcomes back to improve SR scoring" }, { "name": "Merchant Account", "description": "Merchant configuration management" }, { "name": "Routing Rules", "description": "Euclid declarative routing rules engine" }, { "name": "Rule Configuration", "description": "Service-level SR/elimination config" }, { "name": "Config", "description": "Routing key and dimension metadata" }, { "name": "Analytics", "description": "ClickHouse-backed analytics and audit reads" }, { "name": "Compatibility", "description": "Legacy compatibility routes" }, { "name": "Connector Costs" }, { "name": "Merchant Features" }, { "name": "Autopilot" } ], "paths": { "/analytics/decisions": { "get": { "operationId": "analyticsDecisions", "tags": [ "Analytics" ], "summary": "Decisions", "description": "ClickHouse-backed decisions read endpoint.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "description": "Tenant to resolve. The shipped config files define only the \"public\" tenant. No fallback \u2014 omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "start_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "end_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "payment_method_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_network", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_is_in", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "auth_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "gateway", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "route", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "flow_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "exclude_routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "merchant_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsDecisionResponse" } } } } } } }, "/analytics/gateway-scores": { "get": { "operationId": "analyticsGatewayScores", "tags": [ "Analytics" ], "summary": "Gateway scores", "description": "ClickHouse-backed gateway scores read endpoint.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "description": "Tenant to resolve. The shipped config files define only the \"public\" tenant. No fallback \u2014 omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "start_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "end_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "payment_method_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_network", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_is_in", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "auth_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "gateway", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "route", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "flow_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "exclude_routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "merchant_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsGatewayScoresResponse" } } } } } } }, "/analytics/log-summaries": { "get": { "operationId": "analyticsLogSummaries", "tags": [ "Analytics" ], "summary": "Log summaries", "description": "ClickHouse-backed log summaries read endpoint.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "description": "Tenant to resolve. The shipped config files define only the \"public\" tenant. No fallback \u2014 omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "start_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "end_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "payment_method_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_network", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_is_in", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "auth_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "gateway", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "route", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "flow_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "exclude_routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "merchant_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsLogSummariesResponse" } } } } } } }, "/analytics/overview": { "get": { "operationId": "analyticsOverview", "tags": [ "Analytics" ], "summary": "Overview", "description": "ClickHouse-backed overview read endpoint.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "description": "Tenant to resolve. The shipped config files define only the \"public\" tenant. No fallback \u2014 omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "start_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "end_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "payment_method_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_network", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_is_in", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "auth_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "gateway", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "route", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "flow_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "exclude_routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "merchant_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsOverviewResponse" } } } } } } }, "/analytics/payment-audit": { "get": { "operationId": "analyticsPaymentAudit", "tags": [ "Analytics" ], "summary": "Payment audit", "description": "ClickHouse-backed payment audit read endpoint.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "description": "Tenant to resolve. The shipped config files define only the \"public\" tenant. No fallback \u2014 omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "start_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "end_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "payment_method_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_network", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_is_in", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "auth_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "gateway", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "route", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "flow_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "exclude_routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "merchant_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAuditResponse" } } } } } } }, "/analytics/preview-trace": { "get": { "operationId": "analyticsPreviewTrace", "tags": [ "Analytics" ], "summary": "Preview trace", "description": "ClickHouse-backed rule preview trace read endpoint.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "description": "Tenant to resolve. The shipped config files define only the \"public\" tenant. No fallback \u2014 omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "start_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "end_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "payment_method_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_network", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_is_in", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "auth_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "gateway", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "route", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "flow_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "exclude_routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "merchant_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAuditResponse" } } } } } } }, "/analytics/routing-stats": { "get": { "operationId": "analyticsRoutingStats", "tags": [ "Analytics" ], "summary": "Routing stats", "description": "ClickHouse-backed routing stats read endpoint.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "description": "Tenant to resolve. The shipped config files define only the \"public\" tenant. No fallback \u2014 omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "start_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "end_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "payment_method_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_network", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_is_in", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "auth_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "gateway", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "route", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "flow_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "exclude_routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "merchant_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRoutingStatsResponse" } } } } } } }, "/api-key/{key_id}": { "delete": { "operationId": "revokeApiKey", "tags": [ "API Keys" ], "summary": "Revoke API key", "description": "Mark an API key inactive and clear its Redis cache entry.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeApiKeyResponse" } } } } } } }, "/api-key/create": { "post": { "operationId": "createApiKey", "tags": [ "API Keys" ], "summary": "Create API key", "description": "Create a service-to-service API key for a merchant.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "200": { "description": "Created API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } } } } }, "/api-key/list/{merchant_id}": { "get": { "operationId": "listApiKeys", "tags": [ "API Keys" ], "summary": "List API keys", "description": "List active and revoked API keys for a merchant.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API keys", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyListItem" } } } } } } } }, "/auth/login": { "post": { "operationId": "login", "tags": [ "Auth" ], "summary": "Login", "description": "Create a dashboard JWT session.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } } } } }, "/auth/logout": { "post": { "operationId": "logout", "tags": [ "Auth" ], "summary": "Logout", "description": "Revoke the current dashboard JWT.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Logged out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/auth/me": { "get": { "operationId": "me", "tags": [ "Auth" ], "summary": "Current user", "description": "Return current authenticated user and merchant context.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Current user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } } } } }, "/auth/merchants": { "get": { "operationId": "listUserMerchants", "tags": [ "Auth" ], "summary": "List user merchants", "description": "Return merchants available to the current user.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Merchant list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantInfo" } } } } } } } }, "/auth/signup": { "post": { "operationId": "signup", "tags": [ "Auth" ], "summary": "Signup", "description": "Create an operator account. Password must meet dashboard password policy.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupRequest" } } } }, "responses": { "200": { "description": "Authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } } } } }, "/auth/switch-merchant": { "post": { "operationId": "switchMerchant", "tags": [ "Auth" ], "summary": "Switch merchant", "description": "Switch the current dashboard merchant context.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchMerchantRequest" } } } }, "responses": { "200": { "description": "Authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } } } } }, "/config-sr-dimension": { "post": { "operationId": "configSrDimension", "tags": [ "Config" ], "summary": "Configure SR dimensions", "description": "Configure success-rate routing dimensions.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SrDimensionConfig" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/config/routing-keys": { "get": { "operationId": "getRoutingConfig", "tags": [ "Config" ], "summary": "Get routing keys", "description": "Return rule-builder routing keys and supported values.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } } } } }, "/decide-gateway": { "post": { "operationId": "decideGateway", "tags": [ "Gateway Decision" ], "summary": "Decide gateway", "description": "Core routing decision API. Given a payment context and a list of eligible gateways, returns the optimal gateway to route to.\n\nThe engine applies a sequence of filters (currency, card brand, auth type, EMI, etc.) then scores remaining gateways using success rate history, elimination status, and contract obligations.\n\n**Authentication:** Requires either JWT Bearer token or API Key.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideGatewayRequest" }, "examples": { "sr_routing": { "summary": "SR-based routing", "value": { "merchantId": "test_merchant", "paymentInfo": { "paymentId": "pay_001", "amount": 1000, "currency": "USD", "country": "US", "customerId": "cust_123", "paymentType": "ORDER_PAYMENT", "paymentMethodType": "CARD", "paymentMethod": "CREDIT", "authType": "THREE_DS", "cardIsin": "411111" }, "eligibleGatewayList": [ "stripe", "paypal", "adyen" ], "rankingAlgorithm": "SR_BASED_ROUTING", "eliminationEnabled": false } }, "debit_routing": { "summary": "Debit/network-based routing", "value": { "merchantId": "merchant_demo", "paymentInfo": { "paymentId": "debit_001", "amount": 1000, "currency": "USD", "paymentType": "ORDER_PAYMENT", "paymentMethodType": "CARD", "paymentMethod": "DEBIT", "authType": "THREE_DS", "metadata": "{\"merchant_category_code\":\"merchant_category_code_0001\",\"acquirer_country\":\"US\",\"co_badged_card_data\":{\"co_badged_card_networks\":[\"VISA\",\"NYCE\",\"PULSE\",\"STAR\"],\"issuer_country\":\"US\",\"is_regulated\":false,\"regulated_name\":null,\"card_type\":\"debit\"}}" }, "eligibleGatewayList": [ "stripe", "adyen" ], "rankingAlgorithm": "NTW_BASED_ROUTING", "eliminationEnabled": false } }, "hybrid_routing": { "summary": "Hybrid SR + debit routing", "value": { "merchantId": "test_merchant", "paymentInfo": { "paymentId": "pay_003", "amount": 750, "currency": "USD", "paymentType": "ORDER_PAYMENT", "paymentMethodType": "CARD", "paymentMethod": "DEBIT" }, "eligibleGatewayList": [ "stripe", "braintree", "adyen" ], "rankingAlgorithm": "NTW_SR_HYBRID_ROUTING", "eliminationEnabled": false } }, "multi_objective_routing": { "summary": "Multi-objective routing", "value": { "merchantId": "merchant_demo", "paymentInfo": { "paymentId": "mo_001", "amount": 1000, "currency": "USD", "country": "US", "paymentType": "ORDER_PAYMENT", "paymentMethodType": "CARD", "paymentMethod": "CREDIT", "authType": "THREE_DS", "cardIsin": "424242" }, "eligibleGatewayList": [ "stripe", "adyen", "checkout" ], "rankingAlgorithm": "SR_BASED_ROUTING", "eliminationEnabled": true, "enableMultiObjective": true } } } } } }, "responses": { "200": { "description": "Gateway decision result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecidedGateway" }, "examples": { "sr_routing": { "summary": "SR-based routing", "value": { "decided_gateway": "stripe", "routing_approach": "SR_SELECTION_V3_ROUTING", "gateway_priority_map": { "stripe": 0.94, "adyen": 0.87, "paypal": 0.72 }, "routing_dimension": "CARD_BRAND", "routing_dimension_level": "visa", "reset_approach": "NoReset", "is_scheduled_outage": false, "is_rust_based_decider": true, "latency": 8, "multi_objective_info": null } }, "debit_routing": { "summary": "Debit/network-based routing", "value": { "decided_gateway": "stripe", "gateway_priority_map": null, "filter_wise_gateways": null, "priority_logic_tag": null, "routing_approach": "NTW_BASED_ROUTING", "gateway_before_evaluation": null, "priority_logic_output": null, "debit_routing_output": { "co_badged_card_networks_info": [ { "network": "NYCE", "saving_percentage": 1.2 }, { "network": "PULSE", "saving_percentage": 0.9 }, { "network": "VISA", "saving_percentage": 0.1 } ], "issuer_country": "US", "is_regulated": false, "regulated_name": null, "card_type": "debit" }, "reset_approach": "NO_RESET", "routing_dimension": null, "routing_dimension_level": null, "is_scheduled_outage": false, "is_dynamic_mga_enabled": false, "gateway_mga_id_map": null, "is_rust_based_decider": true, "multi_objective_info": null } }, "hybrid_routing": { "summary": "Hybrid SR + debit routing", "value": { "decided_gateway": "stripe", "routing_approach": "NTW_BASED_ROUTING", "debit_routing_output": { "co_badged_card_networks_info": [ { "network": "NYCE", "saving_percentage": 1.2 }, { "network": "PULSE", "saving_percentage": 0.9 } ], "issuer_country": "US", "is_regulated": false, "regulated_name": null, "card_type": "debit" }, "reset_approach": "NO_RESET", "is_scheduled_outage": false, "is_rust_based_decider": true, "multi_objective_info": null } }, "multi_objective_routing": { "summary": "Multi-objective routing \u2014 auth won (SR head retained)", "value": { "decided_gateway": "adyen", "fallback_gateways": [ "stripe", "checkout" ], "gateway_priority_map": { "adyen": 0.65, "checkout": 0.58, "stripe": 0.65 }, "filter_wise_gateways": null, "priority_logic_tag": null, "routing_approach": "SR_SELECTION_V3_ROUTING", "gateway_before_evaluation": "adyen", "priority_logic_output": { "isEnforcement": false, "gws": [ "stripe", "adyen", "checkout" ], "priorityLogicTag": null, "gatewayReferenceIds": {}, "primaryLogic": null, "fallbackLogic": null }, "debit_routing_output": null, "reset_approach": "NO_RESET", "routing_dimension": "ORDER_PAYMENT, CARD, DEBIT, DEBIT", "routing_dimension_level": "CARD_LEVEL", "is_scheduled_outage": false, "is_dynamic_mga_enabled": false, "gateway_mga_id_map": null, "is_rust_based_decider": true, "latency": 3, "multi_objective_info": { "outcome": "AUTH_WON", "reason": "SR head retained \u2014 it is the highest expected-value PSP (3 ranked on EV).", "srHead": { "psp": "adyen", "authRate": 0.65, "costBps": 156.94736842105263 }, "chosen": { "psp": "adyen", "authRate": 0.65, "costBps": 156.94736842105263 }, "costSavedBps": null, "qualifiedCount": 3, "margin": 1, "evGapTop2": 0.013780000000000014 } } }, "multi_objective_cost_won": { "summary": "Multi-objective routing \u2014 cost won (cheaper gateway promoted)", "value": { "decided_gateway": "adyen", "fallback_gateways": [ "stripe", "checkout" ], "gateway_priority_map": { "stripe": 0.94, "adyen": 0.91, "checkout": 0.88 }, "routing_approach": "SR_SELECTION_MULTI_OBJECTIVE", "gateway_before_evaluation": "stripe", "reset_approach": "NO_RESET", "routing_dimension": "ORDER_PAYMENT,CARD,CREDIT,UNKNOWN", "routing_dimension_level": "CARD_LEVEL", "is_scheduled_outage": false, "is_dynamic_mga_enabled": false, "is_rust_based_decider": true, "multi_objective_info": { "outcome": "COST_WON", "reason": "Promoted 'adyen' over 'stripe' on expected value \u2014 saves 80.00 bps for 3.00pp auth.", "srHead": { "psp": "stripe", "authRate": 0.94, "costBps": 180.0 }, "chosen": { "psp": "adyen", "authRate": 0.91, "costBps": 100.0 }, "costSavedBps": 80.0, "qualifiedCount": 3, "margin": 0.2, "evGapTop2": 0.00182 } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/decision_gateway": { "post": { "operationId": "legacyDecisionGateway", "tags": [ "Compatibility" ], "summary": "Legacy decision gateway", "description": "Legacy compatibility route. New integrations should use /decide-gateway.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideGatewayRequest" } } } }, "responses": { "200": { "description": "Gateway decision result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecidedGateway" } } } } } } }, "/health": { "get": { "operationId": "healthCheck", "tags": [ "Health" ], "summary": "Health check", "description": "Service liveness check.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthRespPayload" } } } } } } }, "/health/diagnostics": { "get": { "operationId": "healthDiagnostics", "tags": [ "Health" ], "summary": "Diagnostics", "description": "Database diagnostics for local and deployment troubleshooting.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } } }, "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "description": "Tenant to resolve. The shipped config files define only the \"public\" tenant. No fallback \u2014 omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" } } ] } }, "/health/ready": { "get": { "operationId": "healthReady", "tags": [ "Health" ], "summary": "Readiness check", "description": "Returns Up when the process is ready to serve traffic.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthRespPayload" } } } } } } }, "/merchant-account/create": { "post": { "operationId": "createMerchant", "tags": [ "Merchant Account" ], "summary": "Create merchant", "description": "Register a new merchant account. The merchant ID is the primary identifier used in all subsequent routing and scoring calls.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantAccountCreateResponse" } } } } }, "security": [ { "AdminSecret": [] } ] } }, "/onboarding/merchant": { "post": { "operationId": "onboardMerchant", "tags": [ "Auth" ], "summary": "Create merchant from dashboard", "description": "Create and attach a merchant to the current operator user.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDashboardMerchantRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantResponse" } } } } } } }, "/routing/activate": { "post": { "operationId": "activateRoutingRule", "tags": [ "Routing Rules" ], "summary": "Activate routing rule", "description": "Activate a routing rule by ID for a merchant. Only one rule can be active at a time \u2014 activating a new rule deactivates the previous one.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateRoutingRuleRequest" } } } }, "responses": { "200": { "description": "Rule activated. The response body is empty." } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/routing/deactivate": { "post": { "operationId": "deactivateRoutingRule", "tags": [ "Routing Rules" ], "summary": "Deactivate routing rule", "description": "Deactivate an active routing rule mapping by routing algorithm ID for a merchant. The call is idempotent: if the algorithm exists but is already inactive for the merchant, the API returns success.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeactivateRoutingRuleRequest" } } } }, "responses": { "200": { "description": "Rule deactivated. The response body is empty." }, "400": { "description": "Routing algorithm ID was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/routing/create": { "post": { "operationId": "createRoutingRule", "tags": [ "Routing Rules" ], "summary": "Create routing rule", "description": "Create a new Euclid declarative routing rule for a merchant. Supports `advanced` (full Euclid DSL), `priority` (ordered gateway list), `single` (fixed gateway), and `volume_split` (percentage-based distribution) algorithm types.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoutingRuleRequest" } } } }, "responses": { "200": { "description": "Routing rule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRule" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/routing/evaluate": { "post": { "operationId": "evaluateRoutingRule", "tags": [ "Routing Rules" ], "summary": "Evaluate routing rule", "description": "Evaluate the active routing rule for a merchant against a payment context. Returns the ordered list of gateways selected by the rule without consuming SR data.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingEvaluateResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/routing/hybrid": { "post": { "operationId": "hybridRouting", "tags": [ "Routing Rules" ], "summary": "Hybrid routing evaluation", "description": "Evaluate hybrid routing using the active routing rule plus runtime payment context.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } } } } }, "/routing/list/{created_by}": { "post": { "operationId": "listRoutingRules", "tags": [ "Routing Rules" ], "summary": "List routing rules", "description": "List all routing rules for a merchant.", "parameters": [ { "name": "created_by", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of routing rules", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingRule" } } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/routing/list/active/{created_by}": { "post": { "operationId": "getActiveRoutingRule", "tags": [ "Routing Rules" ], "summary": "Get active routing rule", "description": "Retrieve the currently active routing rule for a merchant.", "parameters": [ { "name": "created_by", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Active routing rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRule" } } } }, "404": { "description": "No active rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/rule/create": { "post": { "operationId": "createRuleConfig", "tags": [ "Rule Configuration" ], "summary": "Create rule config", "description": "Create a service-level configuration for `successRate` or `elimination` scoring. Controls the time window, minimum data thresholds, and other parameters used in SR computation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleConfigRequest" } } } }, "responses": { "200": { "description": "Rule config created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleConfigResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/rule/delete": { "post": { "operationId": "deleteRuleConfig", "tags": [ "Rule Configuration" ], "summary": "Delete rule config", "description": "Delete a rule configuration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleConfigGetRequest" } } } }, "responses": { "200": { "description": "Rule config deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/rule/get": { "post": { "operationId": "getRuleConfig", "tags": [ "Rule Configuration" ], "summary": "Get rule config", "description": "Retrieve an existing rule configuration by merchant and type.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleConfigGetRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleConfig" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/rule/update": { "post": { "operationId": "updateRuleConfig", "tags": [ "Rule Configuration" ], "summary": "Update rule config", "description": "Update an existing rule configuration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleConfigRequest" } } } }, "responses": { "200": { "description": "Rule config updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleConfigResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/update-gateway-score": { "post": { "operationId": "updateGatewayScore", "tags": [ "Score Feedback" ], "summary": "Update gateway score", "description": "Feed a transaction outcome back into the success-rate model. Call this after every transaction so the engine has accurate SR data for future routing decisions.\n\nA `CHARGED` status increases the gateway's SR; failure statuses (`AUTHENTICATION_FAILED`, `AUTHORIZATION_FAILED`, etc.) decrease it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGatewayScoreRequest" }, "example": { "merchantId": "test_merchant", "gateway": "stripe", "paymentId": "pay_001", "status": "CHARGED", "gatewayReferenceId": "stripe_ref_001", "enforceDynamicRoutingFailure": false } } } }, "responses": { "200": { "description": "Score updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScoreResponse" }, "example": { "message": "Score updated", "merchant_id": "test_merchant", "gateway": "stripe", "payment_id": "pay_001" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/update-score": { "post": { "operationId": "legacyUpdateScore", "tags": [ "Compatibility" ], "summary": "Legacy update score", "description": "Legacy compatibility route. New integrations should use /update-gateway-score.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGatewayScoreRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/analytics/cost-savings": { "get": { "operationId": "analyticsCostSavings", "tags": [ "Analytics" ], "summary": "Cost savings", "description": "ClickHouse-backed rollup of savings attributed to multi-objective (cost-aware) routing, trended over the window.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "description": "Tenant to resolve. The shipped config files define only the \"public\" tenant. No fallback \u2014 omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "start_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "end_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "payment_method_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_network", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "card_is_in", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "auth_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "gateway", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "route", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "flow_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "exclude_routing_approach", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "merchant_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsCostSavingsResponse" } } } } } } }, "/analytics/routing-events": { "get": { "operationId": "analyticsRoutingEvents", "tags": [ "Analytics" ], "summary": "Routing events", "description": "Historical feed of routing-relevant state changes: SR leader changes, gateways entering/exiting the multi-objective auth band, and autopilot calibration runs.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "description": "Tenant to resolve. The shipped config files define only the \"public\" tenant. No fallback \u2014 omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "start_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "end_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "payment_method_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "min_transaction_count", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "min_score_delta", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "tolerance_pp", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "bucket", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "merchant_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingEventsResponse" } } } } } } }, "/analytics/experiment/{experiment_id}/results": { "get": { "operationId": "analyticsExperimentResults", "tags": [ "Analytics" ], "summary": "A/B test experiment results", "description": "Statistical significance results (control vs. variant) for a routing A/B test experiment, with guardrail evaluation.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "description": "Tenant to resolve. The shipped config files define only the \"public\" tenant. No fallback \u2014 omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "start_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "end_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "min_sample_size", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "guardrail_threshold_pp", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "evaluation_margin", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "merchant_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "M15", "H1", "H12", "D1", "W1" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentResultsResponse" } } } } } } }, "/analytics/experiment/{experiment_id}/transactions": { "get": { "operationId": "analyticsExperimentTransactions", "tags": [ "Analytics" ], "summary": "A/B test experiment transactions", "description": "Paginated per-transaction log for a routing A/B test experiment, including arm assignment and outcome.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "description": "Tenant to resolve. The shipped config files define only the \"public\" tenant. No fallback \u2014 omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "start_ms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "merchant_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "M15", "H1", "H12", "D1", "W1" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentTransactionsResponse" } } } } } } }, "/merchant-account/{merchant_id}/connectors": { "get": { "operationId": "listConnectorCredentials", "tags": [ "Connector Costs" ], "summary": "List Connector Credentials", "description": "Masked list of connector cost-report credentials configured for the merchant.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MaskedSource" } } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/connectors/{connector}/credentials": { "post": { "operationId": "setConnectorCredentials", "tags": [ "Connector Costs" ], "summary": "Set Connector Credentials", "description": "Store the account and report-download credentials used to pull a connector's cost reports.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" }, { "name": "connector", "in": "path", "required": true, "schema": { "type": "string" }, "example": "adyen" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCredentialsRequest" }, "example": { "account": "MERCHANT_ACCT", "webhook_secret": "whsec_...", "download_auth": "report-user:password" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCredentialsResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/connectors/{connector}/credentials/{account}": { "delete": { "operationId": "deleteConnectorCredentials", "tags": [ "Connector Costs" ], "summary": "Delete Connector Credentials", "description": "Remove a connector account's stored cost-report credentials.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" }, { "name": "connector", "in": "path", "required": true, "schema": { "type": "string" }, "example": "adyen" }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" }, "example": "acct_123" } ], "responses": { "204": { "description": "Deleted" } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/connector-fees": { "get": { "operationId": "listConnectorFees", "tags": [ "Connector Costs" ], "summary": "List Connector Fees", "description": "Per-connector modelled and effective fee rates (model, override and effective pct_bps/fixed).", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorFee" } } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/connectors/{connector}/fee-override": { "put": { "operationId": "setFeeOverride", "tags": [ "Connector Costs" ], "summary": "Set Connector Fee Override", "description": "Manually override the effective fee (pct_bps + fixed) for a connector.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" }, { "name": "connector", "in": "path", "required": true, "schema": { "type": "string" }, "example": "adyen" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFeeOverrideRequest" }, "example": { "pct_bps": 180.0, "fixed": 0.1 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeOverrideResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/cost-clusters": { "get": { "operationId": "listCostClusters", "tags": [ "Connector Costs" ], "summary": "List Cost Clusters", "description": "Learned per-dimension cost clusters (network/funding/country/currency/IC category) with modelled and effective fees.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true } }, { "name": "connector", "in": "query", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "account", "in": "query", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "report_date", "in": "query", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterFee" } } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/cost-clusters/{cluster_key}/fee-override": { "put": { "operationId": "setClusterOverride", "tags": [ "Connector Costs" ], "summary": "Set Cost Cluster Override", "description": "Override the modelled fee for a specific cost cluster identified by its cluster key.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" }, { "name": "cluster_key", "in": "path", "required": true, "schema": { "type": "string" }, "example": "visa|credit|US|USD" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetClusterOverrideRequest" }, "example": { "pct_bps": 210.0, "fixed": 0.12 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterOverride" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/cost-coverage": { "get": { "operationId": "getCostCoverage", "tags": [ "Connector Costs" ], "summary": "Get Cost Coverage", "description": "Summary of how much of the merchant's volume is covered by good (well-modelled) cost clusters.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageSummary" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/cost-ingestions": { "get": { "operationId": "listCostIngestions", "tags": [ "Connector Costs" ], "summary": "List Cost Ingestions", "description": "History of uploaded/pulled cost-report ingestions with staged rows, gross, and status.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IngestionDto" } } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/cost-ingestions/{ingestion_id}": { "delete": { "operationId": "deleteCostIngestion", "tags": [ "Connector Costs" ], "summary": "Delete Cost Ingestion", "description": "Delete a specific cost ingestion and its staged data.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" }, { "name": "ingestion_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "ing_123" } ], "responses": { "204": { "description": "Deleted" } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/cost-price-changes": { "get": { "operationId": "listCostPriceChanges", "tags": [ "Connector Costs" ], "summary": "List Cost Price Changes", "description": "Detected changes in cluster pricing (old vs new pct_bps/fixed) across ingestions.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PriceChange" } } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/invoice-addons": { "get": { "operationId": "listInvoiceAddons", "tags": [ "Connector Costs" ], "summary": "List Invoice Add-ons", "description": "Per-connector periodic-fee add-ons learned from uploaded invoices.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AddonDto" } } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/connectors/{connector}/invoice-addon": { "delete": { "operationId": "deleteInvoiceAddon", "tags": [ "Connector Costs" ], "summary": "Delete Invoice Add-on", "description": "Remove a connector's invoice-derived fee add-on.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" }, { "name": "connector", "in": "path", "required": true, "schema": { "type": "string" }, "example": "adyen" } ], "responses": { "204": { "description": "Deleted" } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/invoice-reconciliation": { "get": { "operationId": "getInvoiceReconciliation", "tags": [ "Connector Costs" ], "summary": "Get Invoice Reconciliation", "description": "Reconciliation of invoice subtotals against modelled + add-on captured fees, per connector.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Reconciliation" } } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/features": { "get": { "operationId": "getMerchantFeatures", "tags": [ "Merchant Features" ], "summary": "Get Merchant Features", "description": "List the merchant's feature-flag states (GSM scoring, explore/exploit, A/B, multi-objective, elimination).", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantFeaturesResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/features/{feature}": { "post": { "operationId": "updateMerchantFeature", "tags": [ "Merchant Features" ], "summary": "Update Merchant Feature", "description": "Enable or disable a single feature flag for the merchant.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "merchant_demo" }, { "name": "feature", "in": "path", "required": true, "schema": { "type": "string" }, "example": "multi-objective-routing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFeatureRequest" }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantFeaturesResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/gateway-score/reset": { "post": { "operationId": "resetGatewayScores", "tags": [ "Autopilot" ], "summary": "Reset Gateway Scores", "description": "Flush a merchant's live gateway (success-rate) scores and any manual overrides.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetGatewayScoresRequest" }, "example": { "merchant_id": "merchant_demo" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetGatewayScoresResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/config-sr-dimension/{merchant_id}": { "get": { "operationId": "getSrDimensions", "tags": [ "Config" ], "summary": "Get SR dimensions", "description": "Retrieve the success-rate routing dimension configuration for a merchant.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SrDimensionConfig" } } } } } } }, "/merchant-account/{merchant_id}": { "get": { "operationId": "getMerchant", "tags": [ "Merchant Account" ], "summary": "Get merchant", "description": "Retrieve a merchant account by ID.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Merchant account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantAccount" } } } }, "404": { "description": "Merchant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "deleteMerchant", "tags": [ "Merchant Account" ], "summary": "Delete merchant", "description": "Delete a merchant account and all associated routing configuration.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Merchant deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchant_id}/debit-routing": { "get": { "operationId": "getMerchantDebitRouting", "tags": [ "Merchant Account" ], "summary": "Get debit routing flag", "description": "Return whether debit/network routing is enabled for a merchant. Missing flag configuration is treated as disabled.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Debit routing flag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitRoutingResponse" } } } }, "404": { "description": "Merchant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "post": { "operationId": "updateMerchantDebitRouting", "tags": [ "Merchant Account" ], "summary": "Update debit routing flag", "description": "Enable or disable runtime debit/network routing for a merchant.", "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitRoutingRequest" } } } }, "responses": { "200": { "description": "Debit routing flag updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitRoutingResponse" } } } }, "404": { "description": "Merchant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token obtained from /auth/login" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key created via /api-key/create" }, "AdminSecret": { "type": "apiKey", "in": "header", "name": "x-admin-secret", "description": "Admin bootstrap secret for creating merchant accounts" } }, "schemas": { "HealthResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Health is good" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "DeleteResponse": { "type": "object", "properties": { "message": { "type": "string" }, "merchant_id": { "type": "string" } } }, "PaymentInfo": { "type": "object", "required": [ "paymentId", "amount", "currency", "paymentType", "paymentMethodType", "paymentMethod" ], "properties": { "paymentId": { "type": "string", "example": "pay_001" }, "amount": { "type": "number", "format": "double", "example": 1000 }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "USD" }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 country code.", "example": "US" }, "customerId": { "type": "string", "nullable": true, "example": "cust_123" }, "udfs": { "type": "object", "nullable": true, "description": "User-defined fields, keyed udf1..udf20.", "additionalProperties": { "type": "string" } }, "preferredGateway": { "type": "string", "nullable": true, "description": "Pins routing to a specific gateway when set." }, "paymentType": { "type": "string", "enum": [ "ORDER_PAYMENT", "MANDATE_REGISTER", "EMANDATE_REGISTER", "MANDATE_PAYMENT", "EMANDATE_PAYMENT", "TPV_PAYMENT", "TPV_EMANDATE_REGISTER", "TPV_MANDATE_REGISTER", "TPV_EMANDATE_PAYMENT", "TPV_MANDATE_PAYMENT", "PARTIAL_CAPTURE", "PARTIAL_VOID", "VAN_PAYMENT", "MOTO_PAYMENT", "UNKNOWN" ], "example": "ORDER_PAYMENT" }, "metadata": { "type": "string", "nullable": true }, "internalMetadata": { "type": "string", "nullable": true }, "isEmi": { "type": "boolean", "nullable": true }, "emiBank": { "type": "string", "nullable": true }, "emiTenure": { "type": "integer", "format": "int32", "nullable": true }, "paymentMethodType": { "type": "string", "description": "Connector-defined payment method type, e.g. CARD, UPI, WALLET, NETBANKING.", "example": "CARD" }, "paymentMethod": { "type": "string", "description": "Connector-defined payment method, e.g. CREDIT, DEBIT, GPAY.", "example": "CREDIT" }, "paymentSource": { "type": "string", "nullable": true }, "authType": { "type": "string", "nullable": true, "enum": [ "ATMPIN", "THREE_DS", "THREE_DS2", "OTP", "OBO_OTP", "VIES", "NO_THREE_DS", "NETWORK_TOKEN", "MOTO", "FIDO", "CTP" ], "example": "THREE_DS" }, "cardIssuerBankName": { "type": "string", "nullable": true }, "cardIsin": { "type": "string", "nullable": true, "example": "411111" }, "cardType": { "type": "string", "nullable": true, "description": "e.g. CREDIT, DEBIT, PREPAID, UPI, NB.", "example": "CREDIT" }, "cardSwitchProvider": { "type": "string", "nullable": true }, "cardProgram": { "type": "string", "nullable": true }, "cardIssuerCountry": { "type": "string", "nullable": true }, "channel": { "type": "string", "nullable": true, "description": "Acceptance channel: ecom / pos / contactless." } } }, "DecideGatewayRequest": { "type": "object", "required": [ "merchantId", "paymentInfo", "eligibleGatewayList", "rankingAlgorithm" ], "properties": { "merchantId": { "type": "string", "example": "test_merchant" }, "paymentInfo": { "$ref": "#/components/schemas/PaymentInfo" }, "eligibleGatewayList": { "type": "array", "items": { "type": "string" }, "example": [ "stripe", "paypal", "adyen" ] }, "rankingAlgorithm": { "type": "string", "enum": [ "SR_BASED_ROUTING", "PL_BASED_ROUTING", "NTW_BASED_ROUTING", "NTW_SR_HYBRID_ROUTING" ], "example": "SR_BASED_ROUTING" }, "eliminationEnabled": { "type": "boolean", "default": false }, "enableMultiObjective": { "type": "boolean", "description": "Per-request override for the multi-objective (cost-aware) post-step. true forces it on, false forces it off; omitted falls back to the merchant's multi_objective_routing_enabled feature flag." } } }, "DecidedGateway": { "type": "object", "properties": { "decided_gateway": { "type": "string", "example": "stripe" }, "routing_approach": { "type": "string", "example": "SR_SELECTION_V3_ROUTING", "description": "Routing approach used. SR_SELECTION_MULTI_OBJECTIVE indicates the multi-objective post-step promoted a cheaper gateway over the SR head." }, "gateway_priority_map": { "type": "object", "additionalProperties": { "type": "number" }, "example": { "stripe": 0.94, "adyen": 0.87, "paypal": 0.72 } }, "routing_dimension": { "type": "string" }, "routing_dimension_level": { "type": "string" }, "reset_approach": { "type": "string" }, "is_scheduled_outage": { "type": "boolean" }, "is_rust_based_decider": { "type": "boolean" }, "debit_routing_output": { "$ref": "#/components/schemas/DebitRoutingOutput" }, "latency": { "type": "number" }, "multi_objective_info": { "allOf": [ { "$ref": "#/components/schemas/MultiObjectiveInfo" } ], "nullable": true, "description": "Populated when the multi-objective post-step ran (multi_objective_routing_enabled feature flag or enableMultiObjective request field, outside hedging). Null otherwise." } } }, "DebitRoutingOutput": { "type": "object", "properties": { "co_badged_card_networks_info": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "example": "NYCE" }, "saving_percentage": { "type": "number", "example": 1.2 } } } }, "issuer_country": { "type": "string", "example": "US" }, "is_regulated": { "type": "boolean", "example": false }, "regulated_name": { "type": "string", "nullable": true }, "card_type": { "type": "string", "example": "Debit" } } }, "UpdateGatewayScoreRequest": { "type": "object", "required": [ "merchantId", "gateway", "paymentId", "status" ], "properties": { "merchantId": { "type": "string", "example": "test_merchant" }, "gateway": { "type": "string", "example": "stripe" }, "paymentId": { "type": "string", "example": "pay_001" }, "status": { "type": "string", "enum": [ "CHARGED", "AUTHENTICATION_FAILED", "AUTHORIZATION_FAILED", "JUSPAY_DECLINED", "FAILURE" ], "example": "CHARGED" }, "gatewayReferenceId": { "type": "string", "example": "stripe_ref_001" }, "enforceDynamicRoutingFailure": { "type": "boolean", "default": false } } }, "UpdateScoreResponse": { "type": "object", "properties": { "message": { "type": "string" }, "merchant_id": { "type": "string" }, "gateway": { "type": "string" }, "payment_id": { "type": "string" } } }, "CreateMerchantRequest": { "type": "object", "required": [ "merchant_id" ], "properties": { "merchant_id": { "type": "string", "example": "my_merchant" }, "gateway_success_rate_based_decider_input": { "type": "string", "nullable": true } } }, "MerchantAccount": { "type": "object", "properties": { "message": { "type": "string" }, "merchant_id": { "type": "string", "example": "my_merchant" }, "gateway_success_rate_based_decider_input": { "type": "string", "nullable": true } } }, "DebitRoutingRequest": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "example": true } } }, "DebitRoutingResponse": { "type": "object", "properties": { "merchant_id": { "type": "string", "example": "my_merchant" }, "debit_routing_enabled": { "type": "boolean", "example": true } } }, "CreateRoutingRuleRequest": { "type": "object", "required": [ "name", "created_by", "algorithm" ], "properties": { "name": { "type": "string", "example": "default-priority" }, "description": { "type": "string", "example": "" }, "created_by": { "type": "string", "example": "test_merchant" }, "algorithm_for": { "type": "string", "enum": [ "payment", "payout", "three_ds_authentication" ], "default": "payment" }, "algorithm": { "$ref": "#/components/schemas/RoutingAlgorithm" }, "metadata": { "type": "object", "nullable": true, "description": "Arbitrary metadata attached to the rule." } } }, "RoutingAlgorithm": { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "enum": [ "priority", "single", "volume_split", "advanced", "ab_test" ], "example": "priority" }, "data": { "description": "Depends on type: array of ConnectorInfo ({gateway_name, gateway_id}) for `priority`; single ConnectorInfo for `single`; array of {split, output} for `volume_split`; Euclid AST Program for `advanced`; ABTestData ({control_algorithm_id, variant_algorithm_id, variant_split_pct, min_sample_size, guardrail_threshold_pp, variant_sr_config?, control_sr_config?}) for `ab_test`" } } }, "ActivateRoutingRuleRequest": { "type": "object", "required": [ "created_by", "routing_algorithm_id" ], "properties": { "created_by": { "type": "string", "example": "test_merchant" }, "routing_algorithm_id": { "type": "string", "example": "rule_abc123" } } }, "DeactivateRoutingRuleRequest": { "type": "object", "required": [ "created_by", "routing_algorithm_id" ], "properties": { "created_by": { "type": "string", "example": "test_merchant" }, "routing_algorithm_id": { "type": "string", "example": "rule_abc123" } } }, "RoutingRule": { "type": "object", "properties": { "rule_id": { "type": "string", "nullable": true, "example": "rule_abc123" }, "name": { "type": "string" }, "description": { "type": "string" }, "created_by": { "type": "string", "example": "test_merchant" }, "algorithm_for": { "type": "string" }, "algorithm": { "$ref": "#/components/schemas/RoutingAlgorithm" }, "metadata": { "type": "object", "nullable": true, "description": "Arbitrary metadata attached to the rule." } } }, "RuleConfigRequest": { "type": "object", "required": [ "merchant_id", "config" ], "properties": { "merchant_id": { "type": "string", "example": "test_merchant" }, "config": { "type": "object", "description": "Tagged config variant. `type` is `successRate`, `elimination`, or `debitRouting`. `data` holds the variant-specific fields." } } }, "RuleConfigGetRequest": { "type": "object", "required": [ "merchant_id", "algorithm" ], "properties": { "merchant_id": { "type": "string", "example": "test_merchant" }, "algorithm": { "type": "string", "enum": [ "successRate", "elimination", "debitRouting" ], "example": "successRate" } } }, "RuleConfigResponse": { "type": "object", "properties": { "message": { "type": "string" }, "merchant_id": { "type": "string" }, "config": { "type": "object" } } }, "GenericObject": { "type": "object", "additionalProperties": true }, "MessageResponse": { "type": "object", "properties": { "message": { "type": "string" } } }, "AuthResponse": { "type": "object", "properties": { "token": { "type": "string" }, "user_id": { "type": "string" }, "email": { "type": "string" }, "merchant_id": { "type": "string" }, "role": { "type": "string" }, "merchants": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantInfo" } } } }, "MerchantInfo": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "merchant_name": { "type": "string" }, "role": { "type": "string" } } }, "CreateDashboardMerchantRequest": { "type": "object", "required": [ "merchant_name" ], "properties": { "merchant_name": { "type": "string", "example": "Demo Merchant" } } }, "SwitchMerchantRequest": { "type": "object", "required": [ "merchant_id" ], "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "merchant_id" ], "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "description": { "type": "string", "nullable": true, "example": "backend integration key" } } }, "CreateApiKeyResponse": { "type": "object", "properties": { "key_id": { "type": "string" }, "api_key": { "type": "string", "example": "DE_..." }, "key_prefix": { "type": "string" }, "merchant_id": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string" } } }, "ApiKeyListItem": { "type": "object", "properties": { "key_id": { "type": "string" }, "key_prefix": { "type": "string" }, "merchant_id": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "created_at": { "type": "string" } } }, "AnalyticsQueryParams": { "type": "object", "properties": { "range": { "type": "string", "enum": [ "15m", "1h", "12h", "1d", "1w" ] }, "start_ms": { "type": "integer", "format": "int64" }, "end_ms": { "type": "integer", "format": "int64" }, "page": { "type": "integer", "minimum": 1 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 50 }, "gateway": { "type": "string" }, "payment_id": { "type": "string" }, "request_id": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "flow_type": { "type": "string" }, "routing_approach": { "type": "string" }, "exclude_routing_approach": { "type": "string" }, "error_code": { "type": "string" } } }, "PspSummary": { "type": "object", "properties": { "psp": { "type": "string", "example": "adyen" }, "authRate": { "type": "number", "example": 0.91 }, "costBps": { "type": "number", "nullable": true, "example": 100.0 } } }, "MultiObjectiveInfo": { "type": "object", "description": "Present when the multi-objective (cost-aware) post-step ran. Explains why the gateway was picked: the SR head was kept (AUTH_WON) or a higher economic-value PSP was promoted (COST_WON). Economic value is auth rate \u00d7 settlement value, where settlement value = txn amount \u2212 cost of payment processing (acquirer, issuer & network fee).", "properties": { "outcome": { "type": "string", "enum": [ "COST_WON", "AUTH_WON" ], "example": "COST_WON" }, "reason": { "type": "string", "example": "Promoted 'adyen' over 'stripe' on expected value \u2014 saves 80.00 bps for 3.00pp auth." }, "srHead": { "allOf": [ { "$ref": "#/components/schemas/PspSummary" } ], "nullable": true, "description": "The PSP the SR scorer would have picked." }, "chosen": { "allOf": [ { "$ref": "#/components/schemas/PspSummary" } ], "nullable": true, "description": "The PSP the post-step actually chose. Equals srHead when auth won." }, "costSavedBps": { "type": "number", "nullable": true, "description": "Fee saved in bps when outcome is COST_WON (srHead.costBps - chosen.costBps).", "example": 80.0 }, "qualifiedCount": { "type": "integer", "description": "Number of PSPs that had cost data and were ranked on expected value.", "example": 3 }, "margin": { "type": "number", "description": "Merchant margin (fraction of ticket) applied for this transaction. Configured via the successRate config margin field; defaults to 1.0.", "example": 0.2 }, "evGapTop2": { "type": "number", "nullable": true, "description": "Expected-value gap between the top-two EV-ranked PSPs, as a fraction of ticket. Null when fewer than two PSPs had cost data.", "example": 0.00182 } } }, "MaskedSource": { "type": "object", "properties": { "connector": { "type": "string" }, "account": { "type": "string" }, "webhook_secret_hint": { "type": "string" }, "download_auth_hint": { "type": "string" } } }, "SetCredentialsRequest": { "type": "object", "properties": { "account": { "type": "string" }, "webhook_secret": { "type": "string" }, "download_auth": { "type": "string" } }, "required": [ "account", "webhook_secret", "download_auth" ] }, "SetCredentialsResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "connector": { "type": "string" }, "account": { "type": "string" }, "status": { "type": "string" } } }, "ConnectorFee": { "type": "object", "properties": { "connector": { "type": "string" }, "account": { "type": "string", "nullable": true }, "has_credentials": { "type": "boolean" }, "model_pct_bps": { "type": "number", "format": "double", "nullable": true }, "model_fixed": { "type": "number", "format": "double", "nullable": true }, "good_gross": { "type": "number", "format": "double", "nullable": true }, "override_pct_bps": { "type": "number", "format": "double", "nullable": true }, "override_fixed": { "type": "number", "format": "double", "nullable": true }, "override_updated_at": { "type": "string", "nullable": true }, "effective_pct_bps": { "type": "number", "format": "double", "nullable": true }, "effective_fixed": { "type": "number", "format": "double", "nullable": true }, "source": { "type": "string" } } }, "SetFeeOverrideRequest": { "type": "object", "properties": { "pct_bps": { "type": "number", "format": "double" }, "fixed": { "type": "number", "format": "double" } }, "required": [ "pct_bps", "fixed" ] }, "FeeOverrideResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "connector": { "type": "string" }, "pct_bps": { "type": "number", "format": "double" }, "fixed": { "type": "number", "format": "double" }, "updated_at": { "type": "string" } } }, "ClusterFee": { "type": "object", "properties": { "key": { "type": "string" }, "connector": { "type": "string" }, "card_network": { "type": "string" }, "variant": { "type": "string" }, "funding": { "type": "string" }, "issuer_country": { "type": "string" }, "currency": { "type": "string" }, "ic_category": { "type": "string" }, "n": { "type": "integer", "format": "int64" }, "gross_sum": { "type": "number", "format": "double" }, "model_pct_bps": { "type": "number", "format": "double", "nullable": true }, "model_fixed": { "type": "number", "format": "double", "nullable": true }, "override_pct_bps": { "type": "number", "format": "double", "nullable": true }, "override_fixed": { "type": "number", "format": "double", "nullable": true }, "override_updated_at": { "type": "string", "nullable": true }, "effective_pct_bps": { "type": "number", "format": "double" }, "effective_fixed": { "type": "number", "format": "double" }, "source": { "type": "string" } } }, "SetClusterOverrideRequest": { "type": "object", "properties": { "pct_bps": { "type": "number", "format": "double" }, "fixed": { "type": "number", "format": "double" } }, "required": [ "pct_bps", "fixed" ] }, "ClusterDims": { "type": "object", "description": "Cluster dimension breakdown (connector, card network, funding, issuer country, currency, IC category).", "additionalProperties": true }, "ClusterOverride": { "type": "object", "properties": { "dims": { "$ref": "#/components/schemas/ClusterDims" }, "pct_bps": { "type": "number", "format": "double" }, "fixed": { "type": "number", "format": "double" }, "updated_at": { "type": "string" } } }, "CoverageSummary": { "type": "object", "properties": { "total_clusters": { "type": "integer", "format": "int64" }, "good_clusters": { "type": "integer", "format": "int64" }, "thin_clusters": { "type": "integer", "format": "int64" }, "non_linear_clusters": { "type": "integer", "format": "int64" }, "total_txns": { "type": "integer", "format": "int64" }, "good_txns": { "type": "integer", "format": "int64" }, "thin_txns": { "type": "integer", "format": "int64" }, "non_linear_txns": { "type": "integer", "format": "int64" }, "good_txn_pct": { "type": "number", "format": "double" }, "total_gross": { "type": "number", "format": "double" }, "good_gross": { "type": "number", "format": "double" }, "thin_gross": { "type": "number", "format": "double" }, "non_linear_gross": { "type": "number", "format": "double" }, "good_gross_pct": { "type": "number", "format": "double" }, "bps_rmse_p50": { "type": "number", "format": "double" }, "bps_rmse_p90": { "type": "number", "format": "double" }, "report_date": { "type": "string" } } }, "IngestionDto": { "type": "object", "properties": { "id": { "type": "string" }, "connector": { "type": "string" }, "account": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "staged_rows": { "type": "integer", "format": "int64" }, "report_date": { "type": "string", "nullable": true }, "period_start": { "type": "string", "nullable": true }, "period_end": { "type": "string", "nullable": true }, "currency_count": { "type": "integer", "format": "int32" }, "currencies": { "type": "array", "items": { "type": "string" } }, "country_count": { "type": "integer", "format": "int32" }, "countries": { "type": "array", "items": { "type": "string" } }, "total_gross": { "type": "number", "format": "double" }, "total_clusters": { "type": "integer", "format": "int64" }, "good_clusters": { "type": "integer", "format": "int64" }, "last_error": { "type": "string", "nullable": true }, "created_at": { "type": "string" } } }, "PriceChange": { "type": "object", "properties": { "connector": { "type": "string" }, "account": { "type": "string" }, "card_network": { "type": "string" }, "variant": { "type": "string" }, "funding": { "type": "string" }, "issuer_country": { "type": "string" }, "currency": { "type": "string" }, "ic_category": { "type": "string" }, "old_pct_bps": { "type": "number", "format": "double" }, "new_pct_bps": { "type": "number", "format": "double" }, "old_fixed": { "type": "number", "format": "double" }, "new_fixed": { "type": "number", "format": "double" }, "changed_on": { "type": "string" } } }, "StoredAddon": { "type": "object", "properties": { "pct_addon_bps": { "type": "number", "format": "double" }, "fixed_addon": { "type": "number", "format": "double" }, "invoice_ref": { "type": "string" }, "subtotal_ex_tax": { "type": "number", "format": "double", "nullable": true }, "card_volume": { "type": "number", "format": "double", "nullable": true }, "txn_count": { "type": "integer", "format": "int64", "nullable": true }, "currency": { "type": "string" }, "period_start": { "type": "string", "nullable": true }, "period_end": { "type": "string", "nullable": true }, "updated_at": { "type": "string" } } }, "AddonDto": { "type": "object", "properties": { "connector": { "type": "string" }, "addon": { "$ref": "#/components/schemas/StoredAddon" } } }, "Reconciliation": { "type": "object", "properties": { "connector": { "type": "string" }, "invoice_subtotal": { "type": "number", "format": "double" }, "model_captured": { "type": "number", "format": "double" }, "addon_contribution": { "type": "number", "format": "double" }, "model_all_in": { "type": "number", "format": "double" }, "residual": { "type": "number", "format": "double" }, "coverage_before": { "type": "number", "format": "double" }, "coverage_after": { "type": "number", "format": "double" } } }, "MerchantFeatureEntry": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "gsm-scoring-filter", "explore-exploit-srv3", "ab-test-real-payments", "multi-objective-routing", "elimination" ] }, "enabled": { "type": "boolean" } } }, "MerchantFeaturesResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantFeatureEntry" } } } }, "UpdateFeatureRequest": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "ResetGatewayScoresRequest": { "type": "object", "properties": { "merchant_id": { "type": "string" } }, "required": [ "merchant_id" ] }, "ResetGatewayScoresResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "deleted_keys": { "type": "integer", "format": "int64" }, "removed_overrides": { "type": "integer", "format": "int64" } } }, "SrDimensionInfo": { "type": "object", "required": [ "udfs" ], "properties": { "udfs": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "fields": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "currency", "country", "auth_type", "card_is_in", "card_network" ] }, "description": "Success-rate routing dimensions. Must be from the eligible set." } } }, "SrDimensionConfig": { "type": "object", "required": [ "merchant_id", "paymentInfo" ], "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "paymentInfo": { "$ref": "#/components/schemas/SrDimensionInfo" } } }, "AnalyticsKpi": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" }, "subtitle": { "type": "string", "nullable": true } } }, "AnalyticsRouteHit": { "type": "object", "properties": { "route": { "type": "string" }, "count": { "type": "integer", "format": "int64" } } }, "AnalyticsRuleHit": { "type": "object", "properties": { "rule_name": { "type": "string", "nullable": true }, "count": { "type": "integer", "format": "int64" } } }, "SmartRetryTrigger": { "type": "object", "properties": { "gateway": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "count": { "type": "integer", "format": "int64" } } }, "SmartRetryFallback": { "type": "object", "properties": { "gateway": { "type": "string" }, "retried": { "type": "integer", "format": "int64" }, "recovered": { "type": "integer", "format": "int64" } } }, "SmartRetryStats": { "type": "object", "properties": { "retried_count": { "type": "integer", "format": "int64" }, "recovered_count": { "type": "integer", "format": "int64" }, "by_trigger": { "type": "array", "items": { "$ref": "#/components/schemas/SmartRetryTrigger" } }, "by_fallback": { "type": "array", "items": { "$ref": "#/components/schemas/SmartRetryFallback" } } } }, "GatewayScoreSnapshot": { "type": "object", "properties": { "merchant_id": { "type": "string", "nullable": true }, "payment_method_type": { "type": "string", "nullable": true }, "payment_method": { "type": "string", "nullable": true }, "gateway": { "type": "string", "nullable": true }, "score_value": { "type": "number", "format": "double", "nullable": true }, "sigma_factor": { "type": "number", "format": "double", "nullable": true }, "average_latency": { "type": "number", "format": "double", "nullable": true }, "tp99_latency": { "type": "number", "format": "double", "nullable": true }, "transaction_count": { "type": "integer", "format": "int64", "nullable": true }, "last_updated_ms": { "type": "integer", "format": "int64" } } }, "GatewayScoreSeriesPoint": { "type": "object", "properties": { "bucket_ms": { "type": "integer", "format": "int64" }, "merchant_id": { "type": "string", "nullable": true }, "payment_method_type": { "type": "string", "nullable": true }, "payment_method": { "type": "string", "nullable": true }, "gateway": { "type": "string", "nullable": true }, "score_value": { "type": "number", "format": "double", "nullable": true } } }, "AnalyticsErrorSummary": { "type": "object", "properties": { "route": { "type": "string", "nullable": true }, "error_code": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "count": { "type": "integer", "format": "int64" }, "last_seen_ms": { "type": "integer", "format": "int64" } } }, "AnalyticsDecisionPoint": { "type": "object", "properties": { "bucket_ms": { "type": "integer", "format": "int64" }, "routing_approach": { "type": "string", "nullable": true }, "count": { "type": "integer", "format": "int64" } } }, "AnalyticsGatewaySharePoint": { "type": "object", "properties": { "bucket_ms": { "type": "integer", "format": "int64" }, "gateway": { "type": "string", "nullable": true }, "count": { "type": "integer", "format": "int64" } } }, "RoutingFilterDimension": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } }, "RoutingFilterDimensionHint": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } } }, "RoutingFilterOptions": { "type": "object", "properties": { "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingFilterDimension" } }, "missing_dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingFilterDimensionHint" } }, "gateways": { "type": "array", "items": { "type": "string" } } } }, "AnalyticsAvailableCurrency": { "type": "object", "properties": { "currency": { "type": "string" }, "decision_count": { "type": "integer", "format": "int64" } } }, "AnalyticsCostSavingsTrendPoint": { "type": "object", "properties": { "bucket_ms": { "type": "integer", "format": "int64" }, "saved_value": { "type": "number", "format": "double" } } }, "AnalyticsCostSavingsTotals": { "type": "object", "properties": { "saved_value": { "type": "number", "format": "double" }, "cost_won_count": { "type": "integer", "format": "int64" }, "total_decisions": { "type": "integer", "format": "int64" } } }, "AnalyticsLogSample": { "type": "object", "properties": { "route": { "type": "string", "nullable": true }, "merchant_id": { "type": "string", "nullable": true }, "payment_id": { "type": "string", "nullable": true }, "request_id": { "type": "string", "nullable": true }, "global_request_id": { "type": "string", "nullable": true }, "trace_id": { "type": "string", "nullable": true }, "gateway": { "type": "string", "nullable": true }, "routing_approach": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "error_code": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "flow_type": { "type": "string", "nullable": true }, "created_at_ms": { "type": "integer", "format": "int64" } } }, "PaymentAuditSummary": { "type": "object", "properties": { "lookup_key": { "type": "string" }, "payment_id": { "type": "string", "nullable": true }, "request_id": { "type": "string", "nullable": true }, "merchant_id": { "type": "string", "nullable": true }, "first_seen_ms": { "type": "integer", "format": "int64" }, "last_seen_ms": { "type": "integer", "format": "int64" }, "event_count": { "type": "integer" }, "latest_status": { "type": "string", "nullable": true }, "latest_gateway": { "type": "string", "nullable": true }, "latest_stage": { "type": "string", "nullable": true }, "gateways": { "type": "array", "items": { "type": "string" } }, "routes": { "type": "array", "items": { "type": "string" } } } }, "PaymentAuditEvent": { "type": "object", "properties": { "id": { "type": "string" }, "flow_type": { "type": "string" }, "event_stage": { "type": "string", "nullable": true }, "route": { "type": "string", "nullable": true }, "merchant_id": { "type": "string", "nullable": true }, "payment_id": { "type": "string", "nullable": true }, "request_id": { "type": "string", "nullable": true }, "global_request_id": { "type": "string", "nullable": true }, "trace_id": { "type": "string", "nullable": true }, "payment_method_type": { "type": "string", "nullable": true }, "payment_method": { "type": "string", "nullable": true }, "gateway": { "type": "string", "nullable": true }, "routing_approach": { "type": "string", "nullable": true }, "rule_name": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "error_code": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "score_value": { "type": "number", "format": "double", "nullable": true }, "sigma_factor": { "type": "number", "format": "double", "nullable": true }, "average_latency": { "type": "number", "format": "double", "nullable": true }, "tp99_latency": { "type": "number", "format": "double", "nullable": true }, "transaction_count": { "type": "integer", "format": "int64", "nullable": true }, "details": { "type": "string", "nullable": true }, "details_json": { "type": "object", "nullable": true }, "created_at_ms": { "type": "integer", "format": "int64" } } }, "ExperimentArmMetrics": { "type": "object", "properties": { "arm": { "type": "string" }, "transaction_count": { "type": "integer", "format": "int64" }, "success_count": { "type": "integer", "format": "int64" }, "failure_count": { "type": "integer", "format": "int64" }, "auth_rate": { "type": "number", "format": "double" }, "first_attempt_auth_rate": { "type": "number", "format": "double" }, "total_cost_saved": { "type": "number", "format": "double", "nullable": true }, "avg_latency_ms": { "type": "number", "format": "double", "nullable": true }, "avg_chosen_cost_bps": { "type": "number", "format": "double", "nullable": true }, "avg_cost_saved_bps": { "type": "number", "format": "double", "nullable": true }, "net_ev_bps": { "type": "number", "format": "double", "nullable": true } } }, "ExperimentTransaction": { "type": "object", "properties": { "payment_id": { "type": "string" }, "variant_arm": { "type": "string" }, "gateway": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "created_at_ms": { "type": "integer", "format": "int64" } } }, "RoutingEvent": { "type": "object", "properties": { "id": { "type": "string" }, "event_type": { "$ref": "#/components/schemas/RoutingEventType" }, "merchant_id": { "type": "string" }, "payment_method_type": { "type": "string", "nullable": true }, "payment_method": { "type": "string", "nullable": true }, "bucket_ms": { "type": "integer", "format": "int64" }, "gateway": { "type": "string" }, "previous_gateway": { "type": "string", "nullable": true }, "score": { "type": "number", "format": "double", "nullable": true }, "previous_score": { "type": "number", "format": "double", "nullable": true }, "transaction_count": { "type": "integer", "format": "int64", "nullable": true }, "bucket_size": { "type": "integer", "format": "int32", "nullable": true }, "previous_bucket_size": { "type": "integer", "format": "int32", "nullable": true }, "hedging_percent": { "type": "number", "format": "double", "nullable": true }, "previous_hedging_percent": { "type": "number", "format": "double", "nullable": true }, "card_network": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "auth_type": { "type": "string", "nullable": true } } }, "AnalyticsOverviewResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "kpis": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsKpi" } }, "route_hits": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsRouteHit" } }, "top_scores": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayScoreSnapshot" } }, "top_errors": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsErrorSummary" } }, "top_rules": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsRuleHit" } }, "smart_retry_stats": { "$ref": "#/components/schemas/SmartRetryStats" } } }, "AnalyticsGatewayScoresResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "range": { "type": "string" }, "snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayScoreSnapshot" } }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayScoreSeriesPoint" } } } }, "AnalyticsDecisionResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "range": { "type": "string" }, "tiles": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsKpi" } }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsDecisionPoint" } }, "approaches": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsRuleHit" } } } }, "AnalyticsRoutingStatsResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "range": { "type": "string" }, "gateway_share": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsGatewaySharePoint" } }, "top_rules": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsRuleHit" } }, "sr_trend": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayScoreSeriesPoint" } }, "available_filters": { "$ref": "#/components/schemas/RoutingFilterOptions" } } }, "AnalyticsCostSavingsResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "range": { "type": "string" }, "currency": { "type": "string", "nullable": true }, "available_currencies": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsAvailableCurrency" } }, "trend": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsCostSavingsTrendPoint" } }, "totals": { "$ref": "#/components/schemas/AnalyticsCostSavingsTotals" } } }, "AnalyticsLogSummariesResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "range": { "type": "string" }, "total_errors": { "type": "integer", "format": "int64" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsErrorSummary" } }, "samples": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsLogSample" } }, "page": { "type": "integer" }, "page_size": { "type": "integer" } } }, "PaymentAuditResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "range": { "type": "string" }, "payment_id": { "type": "string", "nullable": true }, "request_id": { "type": "string", "nullable": true }, "gateway": { "type": "string", "nullable": true }, "route": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "flow_type": { "type": "string", "nullable": true }, "routing_approach": { "type": "string", "nullable": true }, "error_code": { "type": "string", "nullable": true }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total_results": { "type": "integer" }, "total_success": { "type": "integer" }, "total_failure": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentAuditSummary" } }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentAuditEvent" } } } }, "ExperimentResultsResponse": { "type": "object", "properties": { "experiment_id": { "type": "string" }, "merchant_id": { "type": "string" }, "control": { "$ref": "#/components/schemas/ExperimentArmMetrics" }, "variant": { "$ref": "#/components/schemas/ExperimentArmMetrics" }, "delta_pp": { "type": "number", "format": "double" }, "p_value": { "type": "number", "format": "double", "nullable": true }, "confidence_interval": { "type": "array", "items": { "type": "number" }, "nullable": true }, "verdict": { "$ref": "#/components/schemas/ExperimentVerdict" }, "min_sample_size": { "type": "integer", "format": "int32" }, "net_delta_bps": { "type": "number", "format": "double", "nullable": true }, "evaluation_margin": { "type": "number", "format": "double" } } }, "ExperimentTransactionsResponse": { "type": "object", "properties": { "experiment_id": { "type": "string" }, "total": { "type": "integer", "format": "int64" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentTransaction" } } } }, "RoutingEventsResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "range": { "type": "string" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingEvent" } }, "generated_at_ms": { "type": "integer", "format": "int64" } } }, "ExperimentVerdict": { "type": "string", "enum": [ "CollectingData", "NotSignificant", "VariantWins", "VariantLoses", "GuardrailBreached" ] }, "RoutingEventType": { "type": "string", "enum": [ "LeaderChanged", "GatewayEnteredAuthBand", "GatewayExitedAuthBand", "CalibrationApplied" ] }, "RuleConfig": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "config": { "type": "object" } } }, "MerchantAccountCreateResponse": { "type": "object", "properties": { "message": { "type": "string" }, "merchant_id": { "type": "string" }, "gateway_success_rate_based_decider_input": { "type": "string", "nullable": true }, "api_key": { "type": "string", "nullable": true } } }, "RevokeApiKeyResponse": { "type": "object", "properties": { "key_id": { "type": "string" }, "message": { "type": "string" } } }, "CreateMerchantResponse": { "type": "object", "properties": { "token": { "type": "string" }, "merchant_id": { "type": "string" }, "merchant_name": { "type": "string" }, "merchants": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantInfo" } } } }, "HealthRespPayload": { "type": "object", "properties": { "message": { "type": "string" } } }, "ConnectorInfo": { "type": "object", "properties": { "gateway_name": { "type": "string" }, "gateway_id": { "type": "string", "nullable": true } } }, "RoutingEvaluateResponse": { "type": "object", "properties": { "payment_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "output": { "type": "object" }, "evaluated_output": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorInfo" } }, "eligible_connectors": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorInfo" } } } }, "ValueType": { "type": "object", "required": [ "type" ], "description": "Euclid condition value. Tagged by `type`; `value` holds the payload.", "properties": { "type": { "type": "string", "enum": [ "number", "enum_variant", "metadata_variant", "str_value", "global_ref", "number_array", "enum_variant_array", "number_comparison_array" ] }, "value": { "description": "Shape depends on `type`: number->integer, enum_variant/str_value/global_ref->string, number_array/enum_variant_array->array of number/string, number_comparison_array->array of comparisons." } } }, "RoutingRequest": { "type": "object", "required": [ "created_by", "parameters" ], "description": "Request body for POST /routing/evaluate (src/euclid/types.rs::RoutingRequest). No camelCase rename \u2014 snake_case field names.", "properties": { "payment_id": { "type": "string", "nullable": true }, "created_by": { "type": "string", "example": "test_merchant" }, "fallback_output": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ConnectorInfo" }, "description": "Used when the rule evaluation yields no eligible connector." }, "parameters": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ValueType" }, "description": "Map of DSL parameter name (e.g. currency, amount, cardType) to its ValueType.", "example": { "currency": { "type": "str_value", "value": "USD" } } } } }, "LoginRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "example": "operator@example.com" }, "password": { "type": "string", "example": "StrongPass#123" } } }, "SignupRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "example": "operator@example.com" }, "password": { "type": "string", "example": "StrongPass#123" }, "merchant_id": { "type": "string", "nullable": true, "example": "merchant_demo" } } } } } }