Skip to content

api-ref.mdx

Latest commit

 

History

History
172 lines (140 loc) · 11 KB

api-ref.mdx

File metadata and controls

172 lines (140 loc) · 11 KB
Raw
title API Guide
description 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.

Create the merchant record that owns your routing config, API keys, and analytics. See [Create Merchant Account](https://github.com/juspay/decision-engine/blob/main/docs/api-refs/merchant-account-create.mdx). Issue a server-to-server API key to authenticate the calls that follow. See [API Keys](https://github.com/juspay/decision-engine/blob/main/docs/api-refs/api-keys.mdx). 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](https://github.com/juspay/decision-engine/blob/main/docs/api-refs/routing-algorithm-create.mdx). Call `/decide-gateway` for each payment to get the connector to use. See [Run Transactions](https://github.com/juspay/decision-engine/blob/main/docs/api-refs/decide-gateway-sr-based.mdx). Report the authorization outcome so scoring and analytics stay accurate. See [Update Gateway Score](https://github.com/juspay/decision-engine/blob/main/docs/api-refs/update-gateway-score.mdx). Inspect gateway scores, decisions, and audit trails. See [Analytics & Audit](https://github.com/juspay/decision-engine/blob/main/docs/api-refs/analytics-endpoints.mdx).

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

Liveness, readiness, and dependency diagnostics. Sign up, log in, switch merchants, and manage API keys. Create, read, delete a merchant, and manage debit routing. Single, priority, volume-split, and advanced rule trees — plus activation. Success-rate and elimination (downtime) scoring config. Choose a connector per payment via `/decide-gateway`. Report authorization outcomes to keep scoring accurate. Overview, gateway scores, decisions, routing stats, and audit. Cost-aware post-step that re-ranks gateways on expected value. Learn real per-gateway fees from settlement reports and invoices. Compare two routing strategies on live traffic with guardrails. 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](https://github.com/juspay/decision-engine/blob/main/docs/api-refs/decide-gateway-multi-objective.mdx).

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.