{ "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": "Cost & Fees", "description": "Connector fee models, cost clusters, seed costs, and coverage" }, { "name": "Cost Ingestion", "description": "Settlement report and invoice ingestion" } ], "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 — omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" }, "example": "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" } } ], "responses": { "200": { "description": "Decisions", "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 — omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" }, "example": "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" } } ], "responses": { "200": { "description": "Gateway scores", "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 — omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" }, "example": "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" } } ], "responses": { "200": { "description": "Log summaries", "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 — omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" }, "example": "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" } } ], "responses": { "200": { "description": "Overview", "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 — omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" }, "example": "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" } } ], "responses": { "200": { "description": "Payment audit", "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 — omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" }, "example": "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" } } ], "responses": { "200": { "description": "Decision trace", "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 — omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" }, "example": "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" } } ], "responses": { "200": { "description": "Routing stats", "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" }, "example": "018f-key-id" } ], "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" }, "example": "merchant_demo" } ], "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.", "security": [], "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/CurrentUserResponse" } } } } } } }, "/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. Requires the deployment's admin secret in `x-admin-secret` unless `user_auth.signup_requires_admin_secret` is set to false in config (it defaults to true).", "security": [ { "AdminSecret": [] } ], "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/SrDimensionConfigRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string", "example": "SR Dimension configuration updated successfully", "description": "Bare JSON string, not an object." } } } } } } }, "/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/RoutingKeysResponse" } } } } } } }, "/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 — 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 — 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 — 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 — 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/DeciderErrorResponse" } } } } } } }, "/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/LegacyDeciderRequest" } } } }, "responses": { "200": { "description": "Gateway decision result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecidedGateway" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeciderErrorResponse" } } } } } } }, "/health": { "get": { "operationId": "healthCheck", "tags": [ "Health" ], "summary": "Health check", "description": "Service liveness check.", "security": [], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "example": { "message": "Health is good" } } } } } } }, "/health/diagnostics": { "get": { "operationId": "healthDiagnostics", "tags": [ "Health" ], "summary": "Diagnostics", "description": "Database diagnostics for local and deployment troubleshooting.", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiagnosticsResponse" } } } } }, "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "description": "Tenant to resolve. The shipped config files define only the \"public\" tenant. No fallback — omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" }, "example": "public" } ] } }, "/health/ready": { "get": { "operationId": "healthReady", "tags": [ "Health" ], "summary": "Readiness check", "description": "Returns Up when the process is ready to serve traffic.", "security": [], "responses": { "200": { "description": "Ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "example": { "message": "Up" } } } }, "400": { "description": "Not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "example": { "message": "Down" } } } } } } }, "/merchant-account/{merchantId}": { "get": { "operationId": "getMerchant", "tags": [ "Merchant Account" ], "summary": "Get merchant", "description": "Retrieve a merchant account by ID.", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "my_merchant" } ], "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/ApiErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "deleteMerchant", "tags": [ "Merchant Account" ], "summary": "Delete merchant", "description": "Delete a merchant account and all associated routing configuration.", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "my_merchant" } ], "responses": { "200": { "description": "Merchant deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/merchant-account/{merchantId}/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": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "my_merchant" } ], "responses": { "200": { "description": "Debit routing flag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitRoutingResponse" }, "example": { "merchant_id": "my_merchant", "debit_routing_enabled": false } } } }, "404": { "description": "Merchant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "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": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "my_merchant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitRoutingRequest" }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "Debit routing flag updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitRoutingResponse" }, "example": { "merchant_id": "my_merchant", "debit_routing_enabled": true } } } }, "404": { "description": "Merchant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/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" }, "example": { "merchant_id": "my_merchant", "gateway_success_rate_based_decider_input": null } } } }, "responses": { "200": { "description": "Merchant created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantAccountCreateResponse" }, "example": { "message": "Merchant created", "merchant_id": "my_merchant", "gateway_success_rate_based_decider_input": null } } } } }, "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/CreateDashboardMerchantResponse" } } } } } } }, "/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 — activating a new rule deactivates the previous one.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateRoutingRuleRequest" }, "example": { "created_by": "test_merchant", "routing_algorithm_id": "rule_abc123" } } } }, "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" }, "example": { "created_by": "test_merchant", "routing_algorithm_id": "rule_abc123" } } } }, "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/ApiErrorResponse" } } } } }, "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" }, "examples": { "priority": { "summary": "Priority-based rule", "value": { "name": "default-priority", "description": "Route to stripe first, fallback to paypal", "created_by": "test_merchant", "algorithm_for": "payment", "algorithm": { "type": "priority", "data": [ { "gateway_name": "stripe", "gateway_id": null }, { "gateway_name": "paypal", "gateway_id": null }, { "gateway_name": "adyen", "gateway_id": null } ] } } }, "volume_split": { "summary": "Volume split rule", "value": { "name": "ab-test-split", "description": "", "created_by": "test_merchant", "algorithm_for": "payment", "algorithm": { "type": "volume_split", "data": [ { "split": 70, "connectors": [ { "gateway_name": "stripe", "gateway_id": null } ] }, { "split": 30, "connectors": [ { "gateway_name": "paypal", "gateway_id": null } ] } ] } } }, "single": { "summary": "Single connector rule", "value": { "name": "always-stripe", "description": "Always route to stripe", "created_by": "test_merchant", "algorithm_for": "payment", "algorithm": { "type": "single", "data": { "gateway_name": "stripe", "gateway_id": null } } } } } } } }, "responses": { "200": { "description": "Routing rule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingDictionaryRecord" } } } } }, "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/EvaluateRoutingRequest" }, "example": { "created_by": "merchant_demo", "payment_id": "rule_decision_001", "parameters": { "payment_method_type": { "type": "enum_variant", "value": "credit" }, "payment_method": { "type": "enum_variant", "value": "card" }, "currency": { "type": "enum_variant", "value": "USD" }, "amount": { "type": "number", "value": 1000 } } } } } }, "responses": { "200": { "description": "Evaluation result with ordered gateway list", "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/HybridRoutingRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HybridRoutingResponse" } } } } } } }, "/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" }, "example": "merchant_demo" } ], "responses": { "200": { "description": "List of routing rules", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JsonifiedRoutingAlgorithm" } } } } } }, "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" }, "example": "test_merchant" } ], "responses": { "200": { "description": "Active routing rule", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JsonifiedRoutingAlgorithm" }, "description": "Active routing algorithms. Empty array when none is active." } } } } }, "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" }, "examples": { "success_rate": { "summary": "Success rate config", "value": { "merchant_id": "test_merchant", "config": { "type": "successRate", "data": { "defaultBucketSize": 20, "defaultLatencyThreshold": null, "defaultHedgingPercent": null } } } }, "elimination": { "summary": "Elimination config", "value": { "merchant_id": "test_merchant", "config": { "type": "elimination", "data": { "threshold": 0.25 } } } } } } } }, "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" }, "example": { "merchant_id": "test_merchant", "algorithm": "successRate" } } } }, "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" }, "example": { "merchant_id": "test_merchant", "algorithm": "successRate" } } } }, "responses": { "200": { "description": "Rule config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleConfigGetResponse" } } } } }, "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" }, "example": { "merchant_id": "test_merchant", "config": { "type": "successRate", "data": { "defaultBucketSize": 30, "defaultHedgingPercent": 0.1 } } } } } }, "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/LegacyUpdateScoreRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string", "example": "Success", "description": "Bare JSON string, not an object." } } } } } } }, "/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 — omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" }, "example": "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" } } ], "responses": { "200": { "description": "Cost savings", "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 — omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" }, "example": "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" } } ], "responses": { "200": { "description": "Routing events", "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 — omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" }, "example": "public" }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "routing_a1b2c3d4-1111-2222-3333-444455556666" }, { "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" } } ], "responses": { "200": { "description": "A/B test experiment results", "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 — omitting this fails with TE_03.", "schema": { "type": "string", "default": "public" }, "example": "public" }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "routing_a1b2c3d4-1111-2222-3333-444455556666" }, { "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" } } ], "responses": { "200": { "description": "A/B test experiment transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentTransactionsResponse" } } } } } } }, "/merchant-account/{merchantId}/connectors": { "get": { "operationId": "listConnectorCredentials", "tags": [ "Cost Ingestion" ], "summary": "List connector credentials", "description": "List the connector credentials configured for a merchant. Secrets are masked.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" } ], "responses": { "200": { "description": "Masked credentials", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MaskedSource" } } } } } } } }, "/merchant-account/{merchantId}/connectors/{connector}/credentials": { "post": { "operationId": "setConnectorCredentials", "tags": [ "Cost Ingestion" ], "summary": "Set connector credentials", "description": "Store the webhook secret and report-download credential for one connector account.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" }, { "name": "connector", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connector slug.", "example": "adyen" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCredentialsRequest" } } } }, "responses": { "200": { "description": "Credentials stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCredentialsResponse" } } } } } } }, "/merchant-account/{merchantId}/connectors/{connector}/credentials/{account}": { "delete": { "operationId": "deleteConnectorCredentials", "tags": [ "Cost Ingestion" ], "summary": "Delete connector credentials", "description": "Remove the stored credentials for one connector account.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" }, { "name": "connector", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connector slug.", "example": "adyen" }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connector-side account." } ], "responses": { "204": { "description": "Credentials deleted (no body)" } } } }, "/merchant-account/{merchantId}/connector-fees": { "get": { "operationId": "listConnectorFees", "tags": [ "Cost & Fees" ], "summary": "List connector fees", "description": "Per-connector blended fee: the learned model, any manual override, and which of the two is actually used at decide time.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" } ], "responses": { "200": { "description": "Connector fees", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorFee" } } } } } } } }, "/merchant-account/{merchantId}/connectors/{connector}/fee-override": { "put": { "operationId": "setFeeOverride", "tags": [ "Cost & Fees" ], "summary": "Set connector fee override", "description": "Pin a connector's fee to a contracted rate, overriding the learned model.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" }, { "name": "connector", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connector slug.", "example": "adyen" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFeeOverrideRequest" } } } }, "responses": { "200": { "description": "Override saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeOverrideResponse" } } } } } } }, "/merchant-account/{merchantId}/cost-clusters": { "get": { "operationId": "listCostClusters", "tags": [ "Cost & Fees" ], "summary": "List cost clusters", "description": "Top cost clusters for a merchant with their learned rate, any override, and the fit verdict.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Top-N cluster cap." }, { "name": "connector", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Scope to one ingested snapshot. Send with `account` and `report_date`." }, { "name": "account", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Connector-side account. Send with `connector` and `report_date`." }, { "name": "report_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Snapshot date, `YYYY-MM-DD`. Send with `connector` and `account`." }, { "name": "ingestion_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Narrow to one ingestion. Required for a per-upload view: two uploads on the same day under the same account share a snapshot." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`txns` ranks by transaction count. Anything else (default) ranks by settled GMV." } ], "responses": { "200": { "description": "Cost clusters", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterFee" } } } } } } } }, "/merchant-account/{merchantId}/cost-clusters/{cluster_key}/fee-override": { "put": { "operationId": "setClusterOverride", "tags": [ "Cost & Fees" ], "summary": "Set cluster fee override", "description": "Pin one cost cluster to a contracted rate.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" }, { "name": "cluster_key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Opaque cluster key from the cost-clusters listing." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetClusterOverrideRequest" } } } }, "responses": { "200": { "description": "Override saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterOverride" } } } } } } }, "/merchant-account/{merchantId}/cost-coverage": { "get": { "operationId": "getCostCoverage", "tags": [ "Cost & Fees" ], "summary": "Get cost model coverage", "description": "How much of the merchant's settled volume the cost model can actually price, plus fit accuracy.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" } ], "responses": { "200": { "description": "Coverage summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageSummary" } } } } } } }, "/merchant-account/{merchantId}/cost-ingestions": { "get": { "operationId": "listCostIngestions", "tags": [ "Cost Ingestion" ], "summary": "List ingestions", "description": "List the merchant's settlement report ingestions and their status.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" } ], "responses": { "200": { "description": "Ingestions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IngestionDto" } } } } } } } }, "/merchant-account/{merchantId}/cost-ingestions/{ingestion_id}": { "delete": { "operationId": "deleteCostIngestion", "tags": [ "Cost Ingestion" ], "summary": "Delete an ingestion", "description": "Delete one ingestion and the data staged from it.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" }, { "name": "ingestion_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Ingestion id." } ], "responses": { "204": { "description": "Ingestion deleted (no body)" } } } }, "/merchant-account/{merchantId}/cost-price-changes": { "get": { "operationId": "listCostPriceChanges", "tags": [ "Cost & Fees" ], "summary": "List detected price changes", "description": "Clusters whose learned price moved between snapshots - a connector repricing, surfaced from the merchant's own settlement data.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" } ], "responses": { "200": { "description": "Price changes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PriceChange" } } } } } } } }, "/merchant-account/{merchantId}/invoice-addons": { "get": { "operationId": "listInvoiceAddons", "tags": [ "Cost Ingestion" ], "summary": "List invoice add-ons", "description": "List the invoice-derived cost add-ons stored per connector.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" } ], "responses": { "200": { "description": "Invoice add-ons", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AddonDto" } } } } } } } }, "/merchant-account/{merchantId}/connectors/{connector}/invoice-addon": { "delete": { "operationId": "deleteInvoiceAddon", "tags": [ "Cost Ingestion" ], "summary": "Delete a connector's invoice add-on", "description": "Remove the stored invoice-derived cost add-on for one connector.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" }, { "name": "connector", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connector slug.", "example": "adyen" } ], "responses": { "204": { "description": "Add-on deleted (no body)" } } } }, "/merchant-account/{merchantId}/invoice-reconciliation": { "get": { "operationId": "getInvoiceReconciliation", "tags": [ "Cost Ingestion" ], "summary": "Get invoice reconciliation", "description": "How much of each connector invoice the cost model accounts for, before and after the invoice add-on.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" } ], "responses": { "200": { "description": "Reconciliation per connector", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceReconciliation" } } } } } } } }, "/merchant-account/{merchantId}/features": { "get": { "operationId": "getMerchantFeatures", "tags": [ "Merchant Account" ], "summary": "Get merchant feature flags", "description": "List every known feature flag and whether it is enabled for this merchant.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" } ], "responses": { "200": { "description": "Feature flags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantFeaturesResponse" } } } } } } }, "/merchant-account/{merchantId}/features/{feature}": { "post": { "operationId": "updateMerchantFeature", "tags": [ "Merchant Account" ], "summary": "Toggle a merchant feature flag", "description": "Enable or disable one feature flag. Returns the merchant's full flag set.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" }, { "name": "feature", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Feature slug.", "example": "multi-objective-routing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFeatureRequest" } } } }, "responses": { "200": { "description": "Updated feature flags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantFeaturesResponse" } } } } } } }, "/gateway-score/reset": { "post": { "operationId": "resetGatewayScores", "tags": [ "Score Feedback" ], "summary": "Reset gateway scores", "description": "Flush the merchant's stored success-rate scores and any score overrides. The router relearns from subsequent traffic.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetGatewayScoresRequest" } } } }, "responses": { "200": { "description": "Scores reset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetGatewayScoresResponse" } } } } } } }, "/config-sr-dimension/{merchant_id}": { "get": { "operationId": "getSrDimensions", "tags": [ "Config" ], "summary": "Get SR dimension config", "description": "Read the merchant's configured success-rate scoring dimensions.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant account id.", "example": "merchant_demo" } ], "responses": { "200": { "description": "SR dimension config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SrDimensionConfigRequest" } } } } } } } }, "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" } } }, "DeleteResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Merchant account deleted successfully" }, "merchant_id": { "type": "string", "example": "merchant_demo" } } }, "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", "example": "USD" }, "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" ], "example": "ORDER_PAYMENT" }, "paymentMethodType": { "type": "string", "example": "CARD" }, "paymentMethod": { "type": "string", "example": "CREDIT" }, "country": { "type": [ "string", "null" ], "example": "US" }, "customerId": { "type": [ "string", "null" ], "example": "cust_123" }, "udfs": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Positional user-defined fields." }, "preferredGateway": { "type": [ "string", "null" ] }, "metadata": { "type": [ "string", "null" ], "description": "JSON-encoded string. Carries debit-routing inputs such as merchant_category_code, acquirer_country and co_badged_card_data." }, "internalMetadata": { "type": [ "string", "null" ] }, "isEmi": { "type": [ "boolean", "null" ] }, "emiBank": { "type": [ "string", "null" ] }, "emiTenure": { "type": [ "integer", "null" ], "format": "int32" }, "paymentSource": { "type": [ "string", "null" ] }, "authType": { "type": [ "string", "null" ], "enum": [ "ATMPIN", "THREE_DS", "THREE_DS_2", "OTP", "OBO_OTP", "VIES", "NO_THREE_DS", "NETWORK_TOKEN", "MOTO", "FIDO", "CTP", null ], "example": "THREE_DS" }, "cardIssuerBankName": { "type": [ "string", "null" ] }, "cardIsin": { "type": [ "string", "null" ], "example": "411111" }, "cardType": { "type": [ "string", "null" ], "enum": [ "AADHAAR", "ATM_CARD", "CASH", "CREDIT", "DEBIT", "NB", "PAYLATER", "PREPAID", "REWARD", "UPI", "WALLET", "VIRTUAL_ACCOUNT", "OTC", "RTP", "CRYPTO", "BLANK", "PAN", null ], "example": "CREDIT" }, "cardSwitchProvider": { "type": [ "string", "null" ], "description": "Card scheme / network." }, "cardProgram": { "type": [ "string", "null" ] }, "cardIssuerCountry": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ], "description": "Acceptance channel: ecom / pos / contactless. Feeds the interchange-category predictor." } } }, "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" }, "fallback_gateways": { "type": "array", "items": { "type": "string" }, "example": [ "adyen" ] }, "gateway_priority_map": { "type": [ "object", "null" ], "additionalProperties": { "type": "number" }, "example": { "stripe": 0.94, "adyen": 0.87 } }, "filter_wise_gateways": { "type": [ "object", "null" ] }, "priority_logic_tag": { "type": [ "string", "null" ] }, "routing_approach": { "type": "string", "example": "SR_SELECTION_V3_ROUTING", "description": "SR_SELECTION_MULTI_OBJECTIVE indicates the multi-objective post-step promoted a cheaper gateway over the SR head." }, "gateway_before_evaluation": { "type": [ "string", "null" ], "description": "Gateway the SR head selected before the multi-objective / debit-routing post-step replaced it." }, "priority_logic_output": { "type": [ "object", "null" ] }, "debit_routing_output": { "oneOf": [ { "$ref": "#/components/schemas/DebitRoutingOutput" }, { "type": "null" } ] }, "reset_approach": { "type": "string", "enum": [ "ELIMINATION_RESET", "SRV2_RESET", "SRV3_RESET", "NO_RESET", "SRV2_ELIMINATION_RESET", "SRV3_ELIMINATION_RESET" ], "example": "NO_RESET" }, "routing_dimension": { "type": [ "string", "null" ] }, "routing_dimension_level": { "type": [ "string", "null" ] }, "is_scheduled_outage": { "type": "boolean" }, "is_dynamic_mga_enabled": { "type": "boolean" }, "gateway_mga_id_map": { "type": [ "object", "null" ] }, "is_rust_based_decider": { "type": "boolean" }, "latency": { "type": [ "integer", "null" ], "format": "int64" }, "multi_objective_info": { "oneOf": [ { "$ref": "#/components/schemas/MultiObjectiveInfo" }, { "type": "null" } ] } } }, "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", "null" ] }, "card_type": { "type": "string", "example": "Debit" } } }, "UpdateGatewayScoreRequest": { "type": "object", "required": [ "merchantId", "gateway", "paymentId", "status" ], "properties": { "merchantId": { "type": "string", "example": "merchant_demo" }, "gateway": { "type": "string", "example": "stripe" }, "paymentId": { "type": "string", "example": "pay_sr_001" }, "status": { "type": "string", "enum": [ "STARTED", "AUTHENTICATION_FAILED", "JUSPAY_DECLINED", "PENDING_VBV", "VBV_SUCCESSFUL", "AUTHORIZED", "AUTHORIZATION_FAILED", "CHARGED", "AUTHORIZING", "COD_INITIATED", "VOIDED", "VOID_INITIATED", "NOP", "CAPTURE_INITIATED", "CAPTURE_FAILED", "VOID_FAILED", "AUTO_REFUNDED", "PARTIAL_CHARGED", "TO_BE_CHARGED", "PENDING", "FAILURE", "DECLINED" ], "example": "CHARGED", "description": "Transaction status. Must be a TxnStatus value - lowercase values such as `success` are rejected." }, "gatewayReferenceId": { "type": [ "string", "null" ], "example": "stripe_ref_001" }, "enforceDynamicRoutingFailure": { "type": [ "boolean", "null" ] }, "txnLatency": { "type": [ "object", "null" ], "properties": { "gatewayLatency": { "type": [ "number", "null" ], "format": "double", "example": 120.5 } }, "description": "Observed gateway latency, in milliseconds." }, "errorInfo": { "type": [ "object", "null" ], "description": "Gateway error details for the GSM-based scoring filter. When present and the merchant flag is on, user/issuer-originated failures are skipped so the gateway is not penalised." }, "isSmartRetry": { "type": [ "boolean", "null" ], "description": "Set by the orchestrator when this call is a smart-retry attempt." } } }, "UpdateScoreResponse": { "type": "object", "properties": { "message": { "type": "string" }, "merchant_id": { "type": "string" }, "gateway": { "type": "string" }, "payment_id": { "type": "string" }, "gsm_info": { "type": [ "object", "null" ], "description": "GSM lookup result. Present only when `errorInfo` was supplied and a matching rule was found." } } }, "CreateMerchantRequest": { "type": "object", "required": [ "merchant_id" ], "properties": { "merchant_id": { "type": "string", "example": "my_merchant" }, "gateway_success_rate_based_decider_input": { "type": [ "string", "null" ] } } }, "MerchantAccount": { "type": "object", "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "gateway_success_rate_based_decider_input": { "type": [ "string", "null" ] } }, "description": "Merchant account as returned by `GET /merchant-account/{merchantId}`." }, "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", "null" ], "description": "Free-form metadata stored with 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, connectors} for `volume_split`, Euclid AST Program for `advanced`, A/B experiment 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" } } }, "EvaluateRoutingRequest": { "type": "object", "required": [ "created_by", "parameters" ], "properties": { "created_by": { "type": "string", "example": "merchant_demo", "description": "Merchant that owns the routing rule." }, "payment_id": { "type": [ "string", "null" ], "example": "rule_decision_001" }, "fallback_output": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ConnectorInfo" }, "description": "Connectors to fall back to when no rule matches." }, "parameters": { "type": "object", "description": "Map of rule-builder key to typed value. A null value means the key is present but unset.", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/ValueType" }, { "type": "null" } ] }, "example": { "payment_method_type": { "type": "enum_variant", "value": "credit" }, "amount": { "type": "number", "value": 1000 } } } } }, "RuleConfigRequest": { "type": "object", "required": [ "merchant_id", "config" ], "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "config": { "$ref": "#/components/schemas/ConfigVariant" } } }, "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", "example": "Success Rate Configuration created successfully" }, "merchant_id": { "type": "string", "example": "merchant_demo" }, "config": { "$ref": "#/components/schemas/ConfigVariant" } } }, "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", "null" ], "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", "null" ] }, "created_at": { "type": "string" } } }, "ApiKeyListItem": { "type": "object", "properties": { "key_id": { "type": "string" }, "key_prefix": { "type": "string" }, "merchant_id": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "created_at": { "type": "string" } } }, "PspSummary": { "type": "object", "properties": { "psp": { "type": "string", "example": "adyen" }, "authRate": { "type": "number", "example": 0.91 }, "costBps": { "type": [ "number", "null" ], "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 × settlement value, where settlement value = txn amount − 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 — saves 80.00 bps for 3.00pp auth." }, "srHead": { "oneOf": [ { "$ref": "#/components/schemas/PspSummary" }, { "type": "null" } ], "description": "The PSP the SR scorer would have picked." }, "chosen": { "oneOf": [ { "$ref": "#/components/schemas/PspSummary" }, { "type": "null" } ], "description": "The PSP the post-step actually chose. Equals srHead when auth won." }, "costSavedBps": { "type": [ "number", "null" ], "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", "null" ], "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 } } }, "ConnectorInfo": { "type": "object", "required": [ "gateway_name" ], "properties": { "gateway_name": { "type": "string", "example": "stripe" }, "gateway_id": { "type": [ "string", "null" ], "example": "mca_111" } }, "description": "A connector as referenced by routing rules. `gateway_id` is the merchant connector account id and may be null." }, "ValueType": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "number", "enum_variant", "metadata_variant", "str_value", "global_ref", "number_array", "enum_variant_array", "number_comparison_array" ], "example": "enum_variant" }, "value": { "description": "Shape depends on `type`: a number for `number`, a string for `enum_variant`/`str_value`/`global_ref`, `{key, value}` for `metadata_variant`, and an array for the `*_array` variants.", "example": "credit" } }, "description": "Tagged rule-builder value. Discover the valid keys and their allowed values with `GET /config/routing-keys`." }, "RoutingEvaluateResponse": { "type": "object", "properties": { "payment_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "example": "success" }, "output": { "type": "object", "description": "Raw output of the matched rule, tagged by algorithm type (`priority`, `single`, `volume_split`, `advanced`)." }, "evaluated_output": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorInfo" } }, "eligible_connectors": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorInfo" } } } }, "RoutingDictionaryRecord": { "type": "object", "properties": { "rule_id": { "type": "string", "example": "routing_e641380c-6f24-4405-8454-5ae6cbceb7a0" }, "name": { "type": "string", "example": "priority rule" }, "algorithm_for": { "type": "string", "example": "payment" }, "created_at": { "type": "string", "example": "2026-04-26 10:00:00.000000" }, "modified_at": { "type": "string", "example": "2026-04-26 10:00:00.000000" } }, "description": "Summary record returned when a routing rule is created." }, "JsonifiedRoutingAlgorithm": { "type": "object", "properties": { "id": { "type": "string", "example": "routing_e641380c-6f24-4405-8454-5ae6cbceb7a0" }, "created_by": { "type": "string", "example": "merchant_demo" }, "name": { "type": "string", "example": "priority rule" }, "description": { "type": "string", "example": "try stripe before adyen" }, "algorithm_data": { "type": "object", "description": "The stored algorithm, tagged by `type` with the variant payload under `data`. See `RoutingAlgorithm`." }, "algorithm_for": { "type": "string", "example": "payment" }, "created_at": { "type": "string", "example": "2026-04-26 10:00:00.000000" }, "modified_at": { "type": "string", "example": "2026-04-26 10:00:00.000000" } }, "description": "Full routing algorithm record as returned by the list endpoints." }, "LegacyDeciderRequest": { "type": "object", "required": [ "orderReference", "orderMetadata", "txnDetail", "txnCardInfo", "merchantAccount" ], "properties": { "orderReference": { "type": "object", "description": "Full internal order object. `merchantId` inside it identifies the merchant." }, "orderMetadata": { "type": "object", "required": [ "partitionKey" ], "properties": { "partitionKey": { "type": [ "string", "null" ], "description": "Required key. May be null." } }, "description": "Full internal order-metadata object. Required. Note: `partitionKey` must be PRESENT in this object (it may be `null`). It is an `Option` field with a custom `deserialize_with` and no `serde(default)`, so serde requires the key even though the value is nullable.", "additionalProperties": true }, "txnDetail": { "type": "object", "required": [ "partitionKey" ], "properties": { "partitionKey": { "type": [ "string", "null" ], "description": "Required key. May be null." } }, "description": "Full internal transaction object. Note: `partitionKey` must be PRESENT in this object (it may be `null`). It is an `Option` field with a custom `deserialize_with` and no `serde(default)`, so serde requires the key even though the value is nullable.", "additionalProperties": true }, "txnCardInfo": { "type": "object", "required": [ "partitionKey" ], "properties": { "partitionKey": { "type": [ "string", "null" ], "description": "Required key. May be null." } }, "description": "Full internal card/payment-method object. Note: `partitionKey` must be PRESENT in this object (it may be `null`). It is an `Option` field with a custom `deserialize_with` and no `serde(default)`, so serde requires the key even though the value is nullable.", "additionalProperties": true }, "merchantAccount": { "type": "object", "description": "Full internal merchant account object." }, "txnOfferDetails": { "type": [ "array", "null" ], "items": { "type": "object", "description": "Internal transaction offer detail." } }, "cardToken": { "type": [ "string", "null" ] }, "txnType": { "type": [ "string", "null" ] }, "shouldCreateMandate": { "type": [ "boolean", "null" ] }, "enforceGatewayList": { "type": [ "array", "null" ], "items": { "type": "string" }, "example": [ "stripe", "adyen" ] }, "priorityLogicOutput": { "type": [ "object", "null" ], "description": "Precomputed priority-logic output." }, "priorityLogicScript": { "type": [ "string", "null" ] }, "isEdccApplied": { "type": [ "boolean", "null" ] }, "shouldConsumeResult": { "type": [ "boolean", "null" ] } }, "description": "Legacy decider payload built from full internal transaction objects. This is NOT the `/decide-gateway` shape. The endpoint rejects the `/decide-gateway` body with a 400. `orderMetadata`, `txnDetail` and `txnCardInfo` must each carry a `partitionKey` key (value may be null)." }, "LegacyUpdateScoreRequest": { "type": "object", "required": [ "txn_detail", "txn_card_info", "log_message" ], "properties": { "txn_detail": { "type": "object", "required": [ "partitionKey", "id", "netAmount", "currency" ], "properties": { "partitionKey": { "type": [ "string", "null" ], "description": "Required key. May be null." }, "id": { "type": "string", "example": "1", "description": "Numeric string. Must be present and parse as an integer - the conversion unwraps the parsed value, so a missing or non-numeric id panics the handler instead of returning a 4xx." }, "netAmount": { "type": "number", "format": "double", "example": 1000.0 }, "currency": { "type": "string", "example": "USD" } }, "additionalProperties": true, "description": "Full internal transaction object." }, "txn_card_info": { "type": "object", "required": [ "partitionKey", "id" ], "properties": { "partitionKey": { "type": [ "string", "null" ], "description": "Required key. May be null." }, "id": { "type": "string", "example": "1", "description": "Numeric string." }, "txnId": { "type": "string" }, "txnDetailId": { "type": "string", "example": "1", "description": "Numeric string." } }, "additionalProperties": true, "description": "Full internal card/payment-method object." }, "log_message": { "type": "string", "example": "Transaction completed" }, "enforce_dynaic_routing_failure": { "type": [ "boolean", "null" ] }, "gateway_reference_id": { "type": [ "string", "null" ] }, "txn_latency": { "type": [ "object", "null" ], "properties": { "gatewayLatency": { "type": [ "number", "null" ], "format": "double" } } } }, "description": "Legacy score-feedback payload built from full internal transaction objects. This is NOT the `/update-gateway-score` shape. `txn_detail` and `txn_card_info` must each carry a `partitionKey` key (value may be null), and their `id` fields are numeric strings." }, "SrDimensionConfigRequest": { "type": "object", "required": [ "merchant_id", "paymentInfo" ], "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "paymentInfo": { "type": "object", "required": [ "udfs" ], "properties": { "udfs": { "type": "array", "items": { "type": "integer", "format": "int32" }, "example": [] }, "fields": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "currency", "country", "auth_type", "card_is_in", "card_network" ] }, "example": [ "currency", "country", "auth_type" ] } } } } }, "MerchantAccountCreateResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Merchant account created successfully" }, "merchant_id": { "type": "string", "example": "merchant_demo" }, "gateway_success_rate_based_decider_input": { "type": [ "string", "null" ] }, "api_key": { "type": [ "string", "null" ], "example": "DE_...", "description": "Default API key minted for the new merchant. Shown only once." } } }, "GatewayWiseExtraScore": { "type": "object", "required": [ "gatewayName", "gatewaySigmaFactor" ], "properties": { "gatewayName": { "type": "string" }, "gatewaySigmaFactor": { "type": "number", "format": "double" } } }, "SRSubLevelInputConfig": { "type": "object", "properties": { "paymentMethodType": { "type": [ "string", "null" ], "example": "CARD" }, "paymentMethod": { "type": [ "string", "null" ], "example": "CREDIT" }, "cardNetwork": { "type": [ "string", "null" ] }, "cardIsIn": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "authType": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ], "description": "`autopilot` for entries managed by the auto-calibrator. Absent for human-authored ones." }, "latencyThreshold": { "type": [ "number", "null" ], "format": "double" }, "bucketSize": { "type": [ "integer", "null" ], "format": "int32", "example": 30 }, "hedgingPercent": { "type": [ "number", "null" ], "format": "double", "example": 0.05 }, "lowerResetFactor": { "type": [ "number", "null" ], "format": "double" }, "upperResetFactor": { "type": [ "number", "null" ], "format": "double" }, "gatewayExtraScore": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/GatewayWiseExtraScore" } } }, "description": "Per-dimension override. Only the dimensions you set are used to scope the override." }, "SuccessRateData": { "type": "object", "properties": { "defaultLatencyThreshold": { "type": [ "number", "null" ], "format": "double" }, "defaultBucketSize": { "type": [ "integer", "null" ], "format": "int32", "example": 20 }, "defaultHedgingPercent": { "type": [ "number", "null" ], "format": "double" }, "defaultLowerResetFactor": { "type": [ "number", "null" ], "format": "double" }, "defaultUpperResetFactor": { "type": [ "number", "null" ], "format": "double" }, "defaultGatewayExtraScore": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/GatewayWiseExtraScore" } }, "subLevelInputConfig": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SRSubLevelInputConfig" } }, "margin": { "type": [ "number", "null" ], "format": "double", "example": 0.2, "description": "Merchant margin as a fraction of ticket, used by the multi-objective expected-value ranking." } } }, "EliminationData": { "type": "object", "required": [ "threshold" ], "properties": { "threshold": { "type": "number", "format": "double", "example": 0.25 }, "txnLatency": { "type": [ "object", "null" ], "properties": { "gatewayLatency": { "type": [ "number", "null" ], "format": "double" } } } } }, "DebitRoutingData": { "type": "object", "required": [ "merchantCategoryCode", "acquirerCountry" ], "properties": { "merchantCategoryCode": { "type": "string" }, "acquirerCountry": { "type": "string" } } }, "ConfigVariant": { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "enum": [ "successRate", "elimination", "debitRouting" ], "example": "successRate" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/SuccessRateData" }, { "$ref": "#/components/schemas/EliminationData" }, { "$ref": "#/components/schemas/DebitRoutingData" } ], "description": "Variant payload selected by `type`. Fields are camelCase." } } }, "RuleConfigGetResponse": { "type": "object", "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "config": { "$ref": "#/components/schemas/ConfigVariant" } }, "description": "`POST /rule/get` returns the stored config without a `message` field." }, "HybridRoutingRequest": { "type": "object", "properties": { "static_routing_request": { "oneOf": [ { "$ref": "#/components/schemas/EvaluateRoutingRequest" }, { "type": "null" } ] }, "dynamic_routing_request": { "oneOf": [ { "$ref": "#/components/schemas/DecideGatewayRequest" }, { "type": "null" } ] } }, "description": "At least one of `static_routing_request` or `dynamic_routing_request` must be provided." }, "HybridRoutingResponse": { "type": "object", "properties": { "static_routing": { "oneOf": [ { "$ref": "#/components/schemas/RoutingEvaluateResponse" }, { "type": "null" } ] }, "dynamic_routing": { "type": [ "object", "null" ], "description": "Decision-gateway result, wrapped as `{status, decision, fallback_connectors}`." }, "evaluated_connectors": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorInfo" }, "description": "Connectors clients should consume. Prefer this over the per-branch outputs." } } }, "RoutingKeyConfig": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "integer", "enum", "udf", "str_value", "global_ref" ], "example": "enum" }, "values": { "type": [ "string", "null" ], "example": "credit, debit, card", "description": "Comma-separated list of allowed values, for `enum` keys." }, "min_value": { "type": [ "integer", "null" ], "format": "int64" }, "max_value": { "type": [ "integer", "null" ], "format": "int64" }, "min_length": { "type": [ "integer", "null" ] }, "max_length": { "type": [ "integer", "null" ] }, "exact_length": { "type": [ "integer", "null" ] }, "regex": { "type": [ "string", "null" ] } } }, "RoutingKeysResponse": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "object", "description": "Map of routing-key name to its metadata.", "additionalProperties": { "$ref": "#/components/schemas/RoutingKeyConfig" } } } }, "DiagnosticsResponse": { "type": "object", "properties": { "key_custodian_locked": { "type": "boolean", "example": false }, "database": { "type": "object", "properties": { "database_connection": { "type": "string", "enum": [ "Working", "Failing" ], "example": "Working" }, "database_read": { "type": "string", "enum": [ "Working", "Failing" ], "example": "Working" }, "database_write": { "type": "string", "enum": [ "Working", "Failing" ], "example": "Working" }, "database_delete": { "type": "string", "enum": [ "Working", "Failing" ], "example": "Working" } } } } }, "CurrentUserResponse": { "type": "object", "properties": { "user_id": { "type": "string", "example": "user_123" }, "email": { "type": "string", "example": "operator@example.com" }, "merchant_id": { "type": "string", "example": "merchant_demo" }, "role": { "type": "string", "example": "admin" }, "email_verified": { "type": "boolean", "example": true }, "merchants": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantInfo" } } }, "description": "`GET /auth/me` does not return a token." }, "CreateDashboardMerchantResponse": { "type": "object", "properties": { "token": { "type": "string", "example": "eyJ...", "description": "Refreshed JWT scoped to the new merchant." }, "merchant_id": { "type": "string", "example": "merchant_9f21a6c0" }, "merchant_name": { "type": "string", "example": "Demo Merchant" }, "merchants": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantInfo" } } } }, "RevokeApiKeyResponse": { "type": "object", "properties": { "key_id": { "type": "string", "example": "018f2c1a-..." }, "message": { "type": "string", "example": "API key revoked successfully" } } }, "AnalyticsKpi": { "type": "object", "properties": { "label": { "type": "string", "example": "Decision events / 1d" }, "value": { "type": "string", "example": "42" }, "subtitle": { "type": [ "string", "null" ] } } }, "AnalyticsRouteHit": { "type": "object", "properties": { "route": { "type": "string", "example": "decide_gateway" }, "count": { "type": "integer", "format": "int64", "example": 42 } } }, "AnalyticsRuleHit": { "type": "object", "properties": { "rule_name": { "type": [ "string", "null" ], "example": "priority rule" }, "count": { "type": "integer", "format": "int64", "example": 12 } } }, "AnalyticsErrorSummary": { "type": "object", "properties": { "route": { "type": [ "string", "null" ], "example": "decide_gateway" }, "error_code": { "type": [ "string", "null" ], "example": "processor_declined" }, "error_message": { "type": [ "string", "null" ], "example": "Card declined by issuer" }, "count": { "type": "integer", "format": "int64", "example": 3 }, "last_seen_ms": { "type": "integer", "format": "int64", "example": 1808624000000 } } }, "GatewayScoreSnapshot": { "type": "object", "properties": { "merchant_id": { "type": [ "string", "null" ] }, "payment_method_type": { "type": [ "string", "null" ], "example": "CARD" }, "payment_method": { "type": [ "string", "null" ], "example": "CREDIT" }, "gateway": { "type": [ "string", "null" ], "example": "adyen" }, "score_value": { "type": [ "number", "null" ], "format": "double", "example": 0.831 }, "sigma_factor": { "type": [ "number", "null" ], "format": "double" }, "average_latency": { "type": [ "number", "null" ], "format": "double" }, "tp99_latency": { "type": [ "number", "null" ], "format": "double" }, "transaction_count": { "type": [ "integer", "null" ], "format": "int64", "example": 214 }, "last_updated_ms": { "type": "integer", "format": "int64", "example": 1808624000000 } } }, "GatewayScoreSeriesPoint": { "type": "object", "properties": { "bucket_ms": { "type": "integer", "format": "int64", "example": 1808624000000 }, "merchant_id": { "type": [ "string", "null" ] }, "payment_method_type": { "type": [ "string", "null" ] }, "payment_method": { "type": [ "string", "null" ] }, "gateway": { "type": [ "string", "null" ] }, "score_value": { "type": [ "number", "null" ], "format": "double" } } }, "SmartRetryStats": { "type": "object", "properties": { "retried_count": { "type": "integer", "format": "int64", "example": 8 }, "recovered_count": { "type": "integer", "format": "int64", "example": 5 }, "by_trigger": { "type": "array", "items": { "type": "object", "properties": { "gateway": { "type": "string" }, "error_code": { "type": [ "string", "null" ] }, "count": { "type": "integer", "format": "int64" } } } }, "by_fallback": { "type": "array", "items": { "type": "object", "properties": { "gateway": { "type": "string" }, "retried": { "type": "integer", "format": "int64" }, "recovered": { "type": "integer", "format": "int64" } } } } } }, "AnalyticsOverviewResponse": { "type": "object", "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "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" } } }, "AnalyticsDecisionPoint": { "type": "object", "properties": { "bucket_ms": { "type": "integer", "format": "int64", "example": 1808624000000 }, "routing_approach": { "type": [ "string", "null" ], "example": "SR_SELECTION_V3_ROUTING" }, "count": { "type": "integer", "format": "int64", "example": 10 } } }, "AnalyticsDecisionResponse": { "type": "object", "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "range": { "type": "string", "example": "1d" }, "tiles": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsKpi" } }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsDecisionPoint" } }, "approaches": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsRuleHit" } } } }, "AnalyticsGatewayScoresResponse": { "type": "object", "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "range": { "type": "string", "example": "1d" }, "snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayScoreSnapshot" } }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayScoreSeriesPoint" } } } }, "AnalyticsLogSample": { "type": "object", "properties": { "route": { "type": [ "string", "null" ], "example": "decide_gateway" }, "merchant_id": { "type": [ "string", "null" ] }, "payment_id": { "type": [ "string", "null" ], "example": "pay_001" }, "request_id": { "type": [ "string", "null" ] }, "global_request_id": { "type": [ "string", "null" ] }, "trace_id": { "type": [ "string", "null" ] }, "gateway": { "type": [ "string", "null" ], "example": "stripe" }, "routing_approach": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "example": "failure" }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "flow_type": { "type": [ "string", "null" ], "example": "gateway_decided" }, "created_at_ms": { "type": "integer", "format": "int64", "example": 1808624000000 } } }, "AnalyticsLogSummariesResponse": { "type": "object", "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "range": { "type": "string", "example": "1d" }, "total_errors": { "type": "integer", "format": "int64", "example": 2 }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsErrorSummary" } }, "samples": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsLogSample" } }, "page": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 10 } } }, "PaymentAuditSummary": { "type": "object", "properties": { "lookup_key": { "type": "string", "example": "pay_sr_001" }, "payment_id": { "type": [ "string", "null" ], "example": "pay_sr_001" }, "request_id": { "type": [ "string", "null" ] }, "merchant_id": { "type": [ "string", "null" ] }, "first_seen_ms": { "type": "integer", "format": "int64" }, "last_seen_ms": { "type": "integer", "format": "int64" }, "event_count": { "type": "integer", "example": 2 }, "latest_status": { "type": [ "string", "null" ], "example": "success" }, "latest_gateway": { "type": [ "string", "null" ], "example": "stripe" }, "latest_stage": { "type": [ "string", "null" ], "example": "gateway_decided" }, "gateways": { "type": "array", "items": { "type": "string" } }, "routes": { "type": "array", "items": { "type": "string" } } } }, "PaymentAuditEvent": { "type": "object", "properties": { "id": { "type": "string", "example": "evt_..." }, "flow_type": { "type": "string", "example": "decision" }, "event_stage": { "type": [ "string", "null" ], "example": "gateway_decided" }, "route": { "type": [ "string", "null" ], "example": "decide_gateway" }, "merchant_id": { "type": [ "string", "null" ] }, "payment_id": { "type": [ "string", "null" ] }, "request_id": { "type": [ "string", "null" ] }, "global_request_id": { "type": [ "string", "null" ] }, "trace_id": { "type": [ "string", "null" ] }, "payment_method_type": { "type": [ "string", "null" ], "example": "CARD" }, "payment_method": { "type": [ "string", "null" ], "example": "CREDIT" }, "gateway": { "type": [ "string", "null" ], "example": "stripe" }, "routing_approach": { "type": [ "string", "null" ] }, "rule_name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "example": "success" }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "score_value": { "type": [ "number", "null" ], "format": "double", "example": 0.94 }, "sigma_factor": { "type": [ "number", "null" ], "format": "double" }, "average_latency": { "type": [ "number", "null" ], "format": "double" }, "tp99_latency": { "type": [ "number", "null" ], "format": "double" }, "transaction_count": { "type": [ "integer", "null" ], "format": "int64" }, "details": { "type": [ "string", "null" ] }, "details_json": { "description": "Arbitrary structured detail payload." }, "created_at_ms": { "type": "integer", "format": "int64", "example": 1808624000000 } } }, "PaymentAuditResponse": { "type": "object", "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "range": { "type": "string", "example": "1d" }, "payment_id": { "type": [ "string", "null" ] }, "request_id": { "type": [ "string", "null" ] }, "gateway": { "type": [ "string", "null" ] }, "route": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "flow_type": { "type": [ "string", "null" ] }, "routing_approach": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "page": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 12 }, "total_results": { "type": "integer", "example": 1 }, "total_success": { "type": "integer", "example": 1 }, "total_failure": { "type": "integer", "example": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentAuditSummary" } }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentAuditEvent" } } } }, "RoutingFilterOptions": { "type": "object", "properties": { "dimensions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "payment_method_type" }, "label": { "type": "string", "example": "Payment Method Type" }, "values": { "type": "array", "items": { "type": "string" }, "example": [ "CARD" ] } } } }, "missing_dimensions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } } } }, "gateways": { "type": "array", "items": { "type": "string" }, "example": [ "adyen", "stripe" ] } } }, "AnalyticsGatewaySharePoint": { "type": "object", "properties": { "bucket_ms": { "type": "integer", "format": "int64", "example": 1808624000000 }, "gateway": { "type": [ "string", "null" ], "example": "adyen" }, "count": { "type": "integer", "format": "int64", "example": 7 } } }, "AnalyticsRoutingStatsResponse": { "type": "object", "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "range": { "type": "string", "example": "1d" }, "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" } } }, "AnalyticsAvailableCurrency": { "type": "object", "properties": { "currency": { "type": "string", "example": "USD" }, "decision_count": { "type": "integer", "format": "int64" } } }, "AnalyticsCostSavingsTrendPoint": { "type": "object", "properties": { "bucket_ms": { "type": "integer", "format": "int64", "example": 1808624000000 }, "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" } } }, "AnalyticsCostSavingsResponse": { "type": "object", "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "range": { "type": "string", "example": "1d" }, "currency": { "type": [ "string", "null" ], "example": "USD" }, "available_currencies": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsAvailableCurrency" } }, "trend": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsCostSavingsTrendPoint" } }, "totals": { "$ref": "#/components/schemas/AnalyticsCostSavingsTotals" } } }, "RoutingEvent": { "type": "object", "properties": { "id": { "type": "string" }, "event_type": { "type": "string", "enum": [ "leader_changed", "gateway_entered_auth_band", "gateway_exited_auth_band", "calibration_applied" ] }, "merchant_id": { "type": "string" }, "payment_method_type": { "type": [ "string", "null" ] }, "payment_method": { "type": [ "string", "null" ] }, "bucket_ms": { "type": "integer", "format": "int64" }, "gateway": { "type": "string" }, "previous_gateway": { "type": [ "string", "null" ] }, "score": { "type": [ "number", "null" ], "format": "double" }, "previous_score": { "type": [ "number", "null" ], "format": "double" }, "transaction_count": { "type": [ "integer", "null" ], "format": "int64" }, "bucket_size": { "type": [ "integer", "null" ], "format": "int32", "description": "Omitted when absent." }, "previous_bucket_size": { "type": [ "integer", "null" ], "format": "int32", "description": "Omitted when absent." }, "hedging_percent": { "type": [ "number", "null" ], "format": "double", "description": "Omitted when absent." }, "previous_hedging_percent": { "type": [ "number", "null" ], "format": "double", "description": "Omitted when absent." }, "card_network": { "type": [ "string", "null" ], "description": "Omitted when absent." }, "currency": { "type": [ "string", "null" ], "description": "Omitted when absent." }, "country": { "type": [ "string", "null" ], "description": "Omitted when absent." }, "auth_type": { "type": [ "string", "null" ], "description": "Omitted when absent." } }, "description": "Fields marked 'omitted when absent' are skipped entirely rather than serialised as null." }, "RoutingEventsResponse": { "type": "object", "properties": { "merchant_id": { "type": "string", "example": "merchant_demo" }, "range": { "type": "string", "example": "1d" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingEvent" } }, "generated_at_ms": { "type": "integer", "format": "int64" } } }, "ExperimentArmMetrics": { "type": "object", "properties": { "arm": { "type": "string", "example": "control" }, "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", "null" ], "format": "double" }, "avg_latency_ms": { "type": [ "number", "null" ], "format": "double" }, "avg_chosen_cost_bps": { "type": [ "number", "null" ], "format": "double" }, "avg_cost_saved_bps": { "type": [ "number", "null" ], "format": "double" }, "net_ev_bps": { "type": [ "number", "null" ], "format": "double" } } }, "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", "description": "Variant minus control auth rate, in percentage points." }, "p_value": { "type": [ "number", "null" ], "format": "double" }, "confidence_interval": { "type": [ "array", "null" ], "items": { "type": "number", "format": "double" }, "minItems": 2, "maxItems": 2, "description": "Lower and upper bound." }, "verdict": { "type": "string", "enum": [ "collecting_data", "not_significant", "variant_wins", "variant_loses", "guardrail_breached" ] }, "min_sample_size": { "type": "integer" }, "net_delta_bps": { "type": [ "number", "null" ], "format": "double" }, "evaluation_margin": { "type": "number", "format": "double" } } }, "ExperimentTransaction": { "type": "object", "properties": { "payment_id": { "type": "string" }, "variant_arm": { "type": "string" }, "gateway": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "created_at_ms": { "type": "integer", "format": "int64" } } }, "ExperimentTransactionsResponse": { "type": "object", "properties": { "experiment_id": { "type": "string" }, "total": { "type": "integer", "format": "int64" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentTransaction" } } } }, "AddonDto": { "allOf": [ { "type": "object", "properties": { "connector": { "type": "string" } } }, { "$ref": "#/components/schemas/StoredAddon" } ], "description": "A connector's stored invoice add-on. The add-on fields are flattened alongside `connector`." }, "ApiClusterSegment": { "type": "object", "properties": { "seg_idx": { "type": "integer" }, "lo": { "type": "number", "format": "double", "description": "Inclusive lower bound of the amount range this piece prices." }, "hi": { "type": "number", "format": "double", "description": "Exclusive upper bound." }, "pct_bps": { "type": [ "number", "null" ], "format": "double" }, "fixed": { "type": [ "number", "null" ], "format": "double" }, "bps_rmse": { "type": [ "number", "null" ], "format": "double" }, "n": { "type": "integer", "format": "int64" }, "gross_sum": { "type": "number", "format": "double" }, "verdict": { "type": "string", "enum": [ "GOOD", "THIN", "NON_LINEAR" ] } } }, "ClusterFee": { "type": "object", "properties": { "key": { "type": "string", "description": "Opaque cluster key, used in the override PUT/DELETE path." }, "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", "description": "Transaction count. 0 for an override-only cluster no longer in the top set." }, "gross_sum": { "type": "number", "format": "double" }, "model_pct_bps": { "type": [ "number", "null" ], "format": "double" }, "model_fixed": { "type": [ "number", "null" ], "format": "double" }, "override_pct_bps": { "type": [ "number", "null" ], "format": "double" }, "override_fixed": { "type": [ "number", "null" ], "format": "double" }, "override_updated_at": { "type": [ "string", "null" ] }, "effective_pct_bps": { "type": [ "number", "null" ], "format": "double", "description": "Null when the cluster has no usable rate at all." }, "effective_fixed": { "type": [ "number", "null" ], "format": "double" }, "source": { "type": "string", "enum": [ "override", "model", "segmented" ] }, "verdict": { "type": "string", "description": "`GOOD`, `THIN`, `NON_LINEAR`, or `\"\"` for an override-only cluster. A non-GOOD rate is shown so it can be corrected - it is not what the router trusts." }, "card_product": { "type": "string", "description": "Issuer BIN's dominant interchange rate as integer bps (`\"115\"`), or `\"\"` when the report carried no PAN." }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/ApiClusterSegment" }, "description": "Recovered per-segment rates for a capped/tiered cluster. Empty for an ordinary GOOD cluster." } } }, "ClusterOverride": { "type": "object", "properties": { "connector": { "type": "string" }, "card_network": { "type": "string" }, "variant": { "type": "string" }, "funding": { "type": "string" }, "issuer_country": { "type": "string" }, "currency": { "type": "string" }, "ic_category": { "type": "string" }, "pct_bps": { "type": "number", "format": "double" }, "fixed": { "type": "number", "format": "double" }, "updated_at": { "type": "string" } }, "description": "Cluster dimensions are flattened into this object alongside the override values." }, "ConnectorFee": { "type": "object", "properties": { "connector": { "type": "string" }, "account": { "type": [ "string", "null" ], "description": "First configured connector-side account, when credentials are set." }, "has_credentials": { "type": "boolean" }, "model_pct_bps": { "type": [ "number", "null" ], "format": "double", "description": "Model-derived blended fee, volume-weighted over GOOD clusters." }, "model_fixed": { "type": [ "number", "null" ], "format": "double" }, "good_gross": { "type": [ "number", "null" ], "format": "double" }, "override_pct_bps": { "type": [ "number", "null" ], "format": "double", "description": "Manual override, when set." }, "override_fixed": { "type": [ "number", "null" ], "format": "double" }, "override_updated_at": { "type": [ "string", "null" ] }, "effective_pct_bps": { "type": [ "number", "null" ], "format": "double", "description": "The fee actually used at decide time." }, "effective_fixed": { "type": [ "number", "null" ], "format": "double" }, "source": { "type": "string", "enum": [ "override", "model", "none" ] } } }, "CoverageSummary": { "type": "object", "properties": { "total_clusters": { "type": "integer", "format": "int64" }, "good_clusters": { "type": "integer", "format": "int64" }, "tiered_clusters": { "type": "integer", "format": "int64", "description": "One line can't price it, but its recovered amount tiers can." }, "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" }, "tiered_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", "description": "Share of transactions with a trustworthy single-line model." }, "priced_txn_pct": { "type": "number", "format": "double", "description": "Share of transactions the router can price: GOOD plus TIERED." }, "total_gross": { "type": "number", "format": "double" }, "good_gross": { "type": "number", "format": "double" }, "tiered_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" }, "priced_gross_pct": { "type": "number", "format": "double", "description": "Share of settled volume the router can price. The real coverage headline." }, "bps_rmse_p50": { "type": "number", "format": "double" }, "bps_rmse_p90": { "type": "number", "format": "double" }, "report_date": { "type": "string", "example": "2026-04-26", "description": "Snapshot these numbers are from." } } }, "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" } } }, "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", "null" ] }, "period_start": { "type": [ "string", "null" ] }, "period_end": { "type": [ "string", "null" ] }, "currency_count": { "type": "integer" }, "currencies": { "type": "array", "items": { "type": "string" } }, "country_count": { "type": "integer" }, "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", "null" ] }, "created_at": { "type": "string" } } }, "InvoiceReconciliation": { "type": "object", "properties": { "connector": { "type": "string" }, "invoice_subtotal": { "type": "number", "format": "double", "description": "Invoice subtotal excluding taxes - the true all-in cost." }, "model_captured": { "type": "number", "format": "double", "description": "What the fit alone captured over the settled book." }, "addon_contribution": { "type": "number", "format": "double" }, "model_all_in": { "type": "number", "format": "double", "description": "`model_captured + addon_contribution`." }, "residual": { "type": "number", "format": "double", "description": "`invoice_subtotal - model_all_in`. Positive means still under-counting." }, "coverage_before": { "type": "number", "format": "double" }, "coverage_after": { "type": "number", "format": "double" } } }, "MaskedSource": { "type": "object", "properties": { "connector": { "type": "string", "example": "adyen" }, "account": { "type": "string", "description": "Connector-side account, e.g. Adyen `merchantAccountCode`." }, "webhook_secret_hint": { "type": "string", "example": "••••a3f9", "description": "`—` when no credential blob is stored or decryptable." }, "download_auth_hint": { "type": "string", "example": "reportuser:••••" } }, "description": "Connector credentials with secrets masked. Secrets are never returned in full." }, "MerchantFeatureEntry": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "gsm-scoring-filter", "explore-exploit-srv3", "ab-test-real-payments", "multi-objective-routing", "elimination", "auto-calibration", "autopilot" ] }, "enabled": { "type": "boolean" } } }, "MerchantFeaturesResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantFeatureEntry" } } } }, "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", "description": "Snapshot date the new price first appeared." } } }, "ResetGatewayScoresRequest": { "type": "object", "required": [ "merchant_id" ], "properties": { "merchant_id": { "type": "string", "example": "merchant_demo", "description": "Also accepted as `merchantId`." } } }, "ResetGatewayScoresResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "deleted_keys": { "type": "integer" }, "removed_overrides": { "type": "integer" } } }, "SetClusterOverrideRequest": { "type": "object", "required": [ "pct_bps", "fixed" ], "properties": { "pct_bps": { "type": "number", "format": "double" }, "fixed": { "type": "number", "format": "double" } } }, "SetCredentialsRequest": { "type": "object", "required": [ "account", "webhook_secret", "download_auth" ], "properties": { "account": { "type": "string", "description": "Connector-side account, e.g. Adyen `merchantAccountCode`." }, "webhook_secret": { "type": "string", "description": "Secret used to verify inbound webhook signatures." }, "download_auth": { "type": "string", "description": "Report-download credential: either Basic auth as `user:password`, or a Report Service API key on its own (sent as `X-API-Key`)." } } }, "SetCredentialsResponse": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "connector": { "type": "string" }, "account": { "type": "string" }, "status": { "type": "string" } } }, "SetFeeOverrideRequest": { "type": "object", "required": [ "pct_bps", "fixed" ], "properties": { "pct_bps": { "type": "number", "format": "double" }, "fixed": { "type": "number", "format": "double" } } }, "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", "null" ], "format": "double" }, "card_volume": { "type": [ "number", "null" ], "format": "double" }, "txn_count": { "type": [ "integer", "null" ], "format": "int64" }, "currency": { "type": "string" }, "period_start": { "type": [ "string", "null" ] }, "period_end": { "type": [ "string", "null" ] }, "updated_at": { "type": "string" } } }, "UpdateFeatureRequest": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "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", "null" ], "example": "merchant_demo", "description": "Attach the new user to an existing merchant." } } }, "DeciderErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "400" }, "error_code": { "type": "string", "example": "DATA_NOT_FOUND" }, "error_message": { "type": "string", "example": "merchant iframe preferences not found" }, "priority_logic_tag": { "type": [ "string", "null" ] }, "routing_approach": { "type": [ "string", "null" ] }, "filter_wise_gateways": { "type": [ "object", "null" ] }, "error_info": { "type": "object", "properties": { "code": { "type": "string", "example": "MERCHANT_IFRAME_PREFERENCES_NOT_FOUND" }, "user_message": { "type": "string" }, "developer_message": { "type": "string" } } }, "priority_logic_output": { "type": [ "object", "null" ] }, "is_dynamic_mga_enabled": { "type": "boolean" } }, "description": "Error envelope returned by the gateway-decision routes." }, "ApiErrorResponse": { "type": "object", "properties": { "code": { "type": "string", "example": "TE_04" }, "message": { "type": "string", "example": "MerchantId not found" }, "data": { "description": "Optional structured detail, usually null." } }, "description": "Generic API error envelope: an error code, a human-readable message, and an optional structured payload." } } } }