Decision Engine API Guide

This guide walks the Decision Engine API in the order you’ll actually use it: set up a merchant, configure how transactions should be routed, send transactions to /decide-gateway, feed outcomes back, and review analytics. Every page below includes ready-to-run curl examples with realistic payloads. For exact request and response schemas plus an interactive playground, use the OpenAPI Reference.

Two reference surfaces are available. Start here for task-oriented flows; switch to the OpenAPI Reference when you need exact schemas.

Surface	Best for
API Guide (this section)	Copy-paste `curl` examples, end-to-end flows, and request variants.
OpenAPI Reference	One page per endpoint with full schemas and a request playground.

Integration flow

A typical integration follows these steps. Each links to the page with the exact request.

Create a merchant

Create the merchant record that owns your routing config, API keys, and analytics. See Create Merchant Account.

Create an API key

Issue a server-to-server API key to authenticate the calls that follow. See API Keys.

Configure routing

Decide how connectors are chosen — a fixed connector, a priority list, a volume split, or an advanced rule tree — then activate it. See Create Routing Algorithm.

Run transactions

Call /decide-gateway for each payment to get the connector to use. See Run Transactions.

Send feedback

Report the authorization outcome so scoring and analytics stay accurate. See Update Gateway Score.

Review analytics

Inspect gateway scores, decisions, and audit trails. See Analytics & Audit.

Environment setup

Set these once in your shell and reuse them across every example.

# Base URL — local source build or Docker Compose
export BASE_URL=http://localhost:8080

# Sandbox (routed through Hyperswitch), when applicable
# export BASE_URL=https://sandbox.hyperswitch.io

# Protected endpoints accept either a dashboard JWT or an API key
export AUTH_HEADER="Authorization: Bearer <jwt_token>"
# export AUTH_HEADER="x-api-key: DE_<api_key>"

# Sandbox-only routing header
export FEATURE_HEADER="x-feature: decision-engine"

# Required on analytics routes, /health/diagnostics, and /gateway-score/reset only.
# "public" is the only tenant the shipped config files define.
export TENANT_HEADER="x-tenant-id: public"

Public routes need no auth. Protected routes include AUTH_HEADER:

curl "$BASE_URL/analytics/overview?range=1d" \
  --header "$AUTH_HEADER" \
  --header "$TENANT_HEADER" \
  --header "$FEATURE_HEADER"

Authentication & access

Access class	Routes	Required headers
Public health	`GET /health`, `GET /health/ready`	None
Public health (tenant-scoped)	`GET /health/diagnostics`	`TENANT_HEADER` — no auth
Public auth entry	`POST /auth/signup`, `POST /auth/login`	None
Admin bootstrap	`POST /merchant-account/create`	Admin secret configured for the deployment
Protected APIs	API keys, merchant reads/deletes, routing, rule config, decisions, score updates, config	`Authorization: Bearer <jwt_token>` or `x-api-key: <api_key>`
Protected APIs (tenant-scoped)	All `GET /analytics/*`, `POST /gateway-score/reset`	The above, plus `TENANT_HEADER`
Sandbox (Hyperswitch)	Same rules, served through `https://sandbox.hyperswitch.io`	Add `x-feature: decision-engine`

TENANT_HEADER (x-tenant-id) has no fallback — omitting it on a route that needs it fails with TE_03: x-tenant-id not found in headers, regardless of a valid AUTH_HEADER. It’s easy to miss because most routes (/decide-gateway, /routing/*, /rule/*, /merchant-account/*, /update-gateway-score, /auth/*, /api-key/*) resolve the tenant internally and need no such header — only the routes listed above do.

Browse by task

Health & Status

Liveness, readiness, and dependency diagnostics.

Authentication & Onboarding

Merchant Accounts

Create, read, delete a merchant, and manage debit routing.

Configure Routing

Single, priority, volume-split, and advanced rule trees — plus activation.

Scoring Configuration

Success-rate and elimination (downtime) scoring config.

Run Transactions

Choose a connector per payment via /decide-gateway.

Feedback & Scoring

Report authorization outcomes to keep scoring accurate.

Analytics & Audit

Overview, gateway scores, decisions, routing stats, and audit.

Multi-Objective Routing

Cost-aware post-step that re-ranks gateways on expected value.

Cost Data Ingestion

Learn real per-gateway fees from settlement reports and invoices.

A/B Testing

Compare two routing strategies on live traffic with guardrails.

Autopilot & Feature Flags

Self-tuning SR scoring, plus every merchant-level toggle.

Ways to route transactions

/decide-gateway supports several strategies, selected per request with rankingAlgorithm.

Strategy	Request value	Guide
Success-rate (auth-rate) based	`SR_BASED_ROUTING`	SR-based routing
Priority-list based	`PL_BASED_ROUTING`	Priority-list routing
Debit / network based	`NTW_BASED_ROUTING`	Debit routing
Network + SR hybrid	`NTW_SR_HYBRID_ROUTING`	Hybrid routing

Multi-objective (cost-aware) routing is not a rankingAlgorithm value. It is a post-step on success-rate scoring, toggled per request with enableMultiObjective or per merchant with the multi_objective_routing_enabled feature flag. When active, responses carry a multi_objective_info block. See Multi-objective routing.

Advanced capabilities

Beyond the core decide/feedback loop, Decision Engine ships several self-contained systems that build on it:

Capability	What it does	Start here
Cost data ingestion	Learns each connector’s actual fee (from settlement reports and invoices) at a per-cluster level, feeding multi-objective routing’s expected-value ranking.	Connector setup → uploads → fees & coverage
A/B testing	Splits traffic between a control and variant routing strategy — auth vs. cost-aware, manual vs. autopilot, or any two saved algorithms — with a guardrail and significance testing.	Create an experiment → read results
Simulation	Preview what any routing algorithm (including an A/B test arm) would decide for a given payment context, without a real transaction.	Evaluate Routing Algorithm
Autopilot & auto-calibration	Background job that self-tunes SR hedging % and bucket size from observed traffic, with a hard-reset endpoint for simulation runs.	Merchant Features

Backward compatibility

Legacy routes are kept for older integrations. New integrations should use /decide-gateway and /update-gateway-score.

Legacy decision endpoint — the older /decision_gateway route.
Legacy update score — the older /update-score route.

Overview

OpenAPI: Health

OpenAPI: Gateway Decision

OpenAPI: Score Feedback

OpenAPI: Merchant Account

OpenAPI: Routing Rules

OpenAPI: Rule Configuration

OpenAPI: Auth And API Keys

OpenAPI: Analytics

OpenAPI: Compatibility And Config

OpenAPI: Connector Costs & Ingestion

OpenAPI: Feature Flags & Autopilot

API Examples (curl flows)

API Guide

Decision Engine API Guide

Integration flow

Environment setup

Authentication & access

Browse by task

Health & Status

Authentication & Onboarding

Merchant Accounts

Configure Routing

Scoring Configuration

Run Transactions

Feedback & Scoring

Analytics & Audit

Multi-Objective Routing

Cost Data Ingestion

A/B Testing

Autopilot & Feature Flags

Ways to route transactions

Advanced capabilities

Backward compatibility

​Decision Engine API Guide

​Integration flow

​Environment setup

​Authentication & access

​Browse by task

Health & Status

Authentication & Onboarding

Merchant Accounts

Configure Routing

Scoring Configuration

Run Transactions

Feedback & Scoring

Analytics & Audit

Multi-Objective Routing

Cost Data Ingestion

A/B Testing

Autopilot & Feature Flags

​Ways to route transactions

​Advanced capabilities

​Backward compatibility

Decision Engine API Guide

Integration flow

Environment setup

Authentication & access

Browse by task

Ways to route transactions

Advanced capabilities

Backward compatibility