API Guide

A practical, copy-paste guide to the Decision Engine API — from creating a merchant to running routed transactions and reading analytics.

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.

1. Create a merchant

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

2. Create an API key

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

3. 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.

4. Run transactions

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

5. Send feedback

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

6. 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

Sign up, log in, switch merchants, and manage API keys.

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.