diff --git a/README.md b/README.md index d79ea724..03652f71 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,9 @@ Open: - API: `http://localhost:8080` - Dashboard: `http://localhost:8081/dashboard/` - Docs: `http://localhost:8081/introduction` -- API examples: `http://localhost:8081/api-refs/api-ref` +- API documentation map: `http://localhost:8081/api-overview` + +For deployed docs or dashboard environments, use the same docs paths under the deployed host, for example `https:///api-overview`. That page links to the API examples and OpenAPI reference sections. ### 🦀 From Source @@ -144,8 +146,7 @@ curl http://localhost:8080/health | [Local Setup Guide](docs/local-setup.md) | Canonical guide for CLI, Docker, Compose profiles, and Helm | | [MySQL Setup Guide](docs/setup-guide-mysql.md) | MySQL-specific walkthrough | | [PostgreSQL Setup Guide](docs/setup-guide-postgres.md) | PostgreSQL-specific walkthrough | -| [API Reference](docs/api-reference.md) | OpenAPI-backed REST API documentation | -| [API Examples](docs/api-refs/api-ref.mdx) | Curl examples for every route family and routing flavour | +| [API Documentation Map](docs/api-overview.md) | Main API entrypoint with embedded links to API examples, OpenAPI schema pages, route access rules, local URLs, and deployed docs paths | | [Configuration Guide](docs/configuration.md) | All config options explained | | [Deep Dive Blog](https://juspay.io/blog/juspay-orchestrator-and-merchant-controlled-routing-engine) | How routing logic works | diff --git a/docs/api-overview.md b/docs/api-overview.md new file mode 100644 index 00000000..f6102233 --- /dev/null +++ b/docs/api-overview.md @@ -0,0 +1,90 @@ +# API Documentation Map + +Decision Engine keeps API documentation in two complementary forms: example-first guides for integration work, and OpenAPI-backed endpoint pages for schema lookup. + +## Start here + +| Page | Use it for | +| --- | --- | +| [API Examples](api-refs/api-ref.mdx) | Copy-paste cURL flows, request variants, rule examples, merchant/API-key CRUD, decision calls, debit routing, analytics, and audit. | +| [OpenAPI Overview](api-reference.md) | Schema-oriented endpoint navigation backed by `docs/openapi.json`. | +| [OpenAPI contract](openapi.json) | Machine-readable contract used by Mintlify and API tooling. | + +## API examples by route family + +| Route family | Example docs | +| --- | --- | +| Health | [Health, readiness, and diagnostics](api-refs/health-check.mdx) | +| Auth and onboarding | [Auth and onboarding](api-refs/auth-and-onboarding.mdx) | +| Merchant CRUD | [Create merchant](api-refs/merchant-account-create.mdx), [get merchant](api-refs/merchant-account-get.mdx), [delete merchant](api-refs/merchant-account-delete.mdx) | +| API key CRUD | [Create, list, and revoke API keys](api-refs/api-keys.mdx) | +| Rule-based routing lifecycle | [Create](api-refs/routing-algorithm-create.mdx), [activate](api-refs/routing-algorithm-activate.mdx), [list](api-refs/routing-algorithm-list.mdx), [list active](api-refs/routing-algorithm-list-active.mdx), [evaluate](api-refs/routing-algorithm-evaluate.mdx), [hybrid](api-refs/routing-hybrid.mdx) | +| Rule algorithm variants | [Single connector](api-refs/routing-single-connector-example.mdx), [priority](api-refs/routing-priority-example.mdx), [volume split](api-refs/routing-volume-split-example.mdx), [advanced AND/OR/nested](api-refs/routing-advanced-example.mdx) | +| Rule config CRUD | [Success-rate create](api-refs/success-rate-config-create.mdx), [get](api-refs/success-rate-config-get.mdx), [update](api-refs/success-rate-config-update.mdx), [delete](api-refs/success-rate-config-delete.mdx), [elimination create](api-refs/elimination-config-create.mdx), [get](api-refs/elimination-config-get.mdx), [update](api-refs/elimination-config-update.mdx), [delete](api-refs/elimination-config-delete.mdx) | +| Decide gateway transactions | [SR-based](api-refs/decide-gateway-sr-based.mdx), [priority-list](api-refs/decide-gateway-pl-based.mdx), [debit/network](api-refs/decide-gateway-debit-routing.mdx), [network + SR hybrid](api-refs/decide-gateway-hybrid-routing.mdx) | +| Score update | [Update gateway score](api-refs/update-gateway-score.mdx), [legacy update score](api-refs/update-score-legacy.mdx) | +| Debit routing | [Merchant debit-routing flag](api-refs/merchant-debit-routing.mdx), [debit transaction request](api-refs/decide-gateway-debit-routing.mdx) | +| Config | [Routing config endpoints](api-refs/config-endpoints.mdx) | +| Analytics and audit | [Analytics endpoints](api-refs/analytics-endpoints.mdx) | +| Compatibility | [Legacy decision endpoint](api-refs/decision-gateway-legacy.mdx), [legacy update score](api-refs/update-score-legacy.mdx) | + +## OpenAPI endpoint pages + +Use these when you need schema-backed endpoint pages or Mintlify playground metadata: + +| Family | OpenAPI docs | +| --- | --- | +| Health | [Health](api-reference/endpoint/healthCheck.mdx), [ready](api-reference/endpoint/healthReady.mdx), [diagnostics](api-reference/endpoint/healthDiagnostics.mdx) | +| Auth and onboarding | [Signup](api-reference/endpoint/signup.mdx), [login](api-reference/endpoint/login.mdx), [logout](api-reference/endpoint/logout.mdx), [me](api-reference/endpoint/me.mdx), [merchants](api-reference/endpoint/listUserMerchants.mdx), [switch merchant](api-reference/endpoint/switchMerchant.mdx), [onboard merchant](api-reference/endpoint/onboardMerchant.mdx) | +| API keys | [Create](api-reference/endpoint/createApiKey.mdx), [list](api-reference/endpoint/listApiKeys.mdx), [revoke](api-reference/endpoint/revokeApiKey.mdx) | +| Merchant account | [Create](api-reference/endpoint/createMerchant.mdx), [get](api-reference/endpoint/getMerchant.mdx), [delete](api-reference/endpoint/deleteMerchant.mdx), [get debit routing](api-reference/endpoint/getMerchantDebitRouting.mdx), [update debit routing](api-reference/endpoint/updateMerchantDebitRouting.mdx) | +| Routing | [Create](api-reference/endpoint/createRoutingRule.mdx), [activate](api-reference/endpoint/activateRoutingRule.mdx), [list](api-reference/endpoint/listRoutingRules.mdx), [active](api-reference/endpoint/getActiveRoutingRule.mdx), [evaluate](api-reference/endpoint/evaluateRoutingRule.mdx), [hybrid](api-reference/endpoint/hybridRouting.mdx) | +| Rule config | [Create](api-reference/endpoint/createRuleConfig.mdx), [get](api-reference/endpoint/getRuleConfig.mdx), [update](api-reference/endpoint/updateRuleConfig.mdx), [delete](api-reference/endpoint/deleteRuleConfig.mdx) | +| Decision and score | [Decide gateway](api-reference/endpoint/decideGateway.mdx), [legacy decision gateway](api-reference/endpoint/legacyDecisionGateway.mdx), [update gateway score](api-reference/endpoint/updateGatewayScore.mdx), [legacy update score](api-reference/endpoint/legacyUpdateScore.mdx) | +| Config | [Routing keys](api-reference/endpoint/getRoutingConfig.mdx), [SR dimensions](api-reference/endpoint/configSrDimension.mdx) | +| Analytics | [Overview](api-reference/endpoint/analyticsOverview.mdx), [gateway scores](api-reference/endpoint/analyticsGatewayScores.mdx), [decisions](api-reference/endpoint/analyticsDecisions.mdx), [routing stats](api-reference/endpoint/analyticsRoutingStats.mdx), [log summaries](api-reference/endpoint/analyticsLogSummaries.mdx), [payment audit](api-reference/endpoint/analyticsPaymentAudit.mdx), [preview trace](api-reference/endpoint/analyticsPreviewTrace.mdx) | + +## Local docs URLs + +When running the dashboard/docs Compose profile, docs are available through the local Nginx route: + +```text +http://localhost:8081/introduction +http://localhost:8081/api-overview +http://localhost:8081/api-refs/api-ref +http://localhost:8081/api-reference +``` + +## Deployed docs URLs + +For a deployed docs/dashboard host, use the same paths under the deployed base URL: + +```text +https:///introduction +https:///api-overview +https:///api-refs/api-ref +https:///api-reference +``` + +If the dashboard is hosted under a prefix such as `/decision-engine/`, the docs proxy should preserve the same page paths under that prefix. + +## Route access classes + +| Access class | Routes | Authentication | +| --- | --- | --- | +| Public | `GET /health`, `GET /health/ready`, `GET /health/diagnostics`, `POST /auth/signup`, `POST /auth/login` | None | +| Admin bootstrap | `POST /merchant-account/create` | Admin secret configured for the deployment | +| Protected | Routing, decision, score update, rule config, API key, merchant read/delete, analytics, audit, config, and authenticated auth routes | `Authorization: Bearer ` or `x-api-key: ` | +| Sandbox | Same routes through `https://sandbox.hyperswitch.io` | Same auth rules plus `x-feature: decision-engine` | + +## Common flows + +| Flow | Primary docs | +| --- | --- | +| Merchant CRUD | [API Examples: Merchant CRUD](api-refs/api-ref.mdx#merchant-crud) | +| API key CRUD | [API Examples: API Key CRUD](api-refs/api-ref.mdx#api-key-crud) | +| Rule-based routing lifecycle | [Create routing algorithm](api-refs/routing-algorithm-create.mdx) | +| Advanced AND/OR/nested rules | [Advanced rule tree](api-refs/routing-advanced-example.mdx) | +| Decide-gateway transactions | [SR-based routing](api-refs/decide-gateway-sr-based.mdx) | +| Debit routing | [Debit-routing merchant flag](api-refs/merchant-debit-routing.mdx) | +| Analytics and audit | [Analytics endpoints](api-refs/analytics-endpoints.mdx) | diff --git a/docs/api-reference.md b/docs/api-reference.md index 81551b4e..0afea5f9 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -2,6 +2,25 @@ The canonical OpenAPI contract for the docs site is `docs/openapi.json`. Use this page for schema-oriented navigation. Use [API Examples](./api-refs/api-ref.mdx) for curl-first flows, valid payloads, and route variants. +## Docs surfaces + +| Surface | What it is for | Path | +| --- | --- | --- | +| API Examples | Public integration guide with cURL flows, variants, and working payloads. | [`docs/api-refs/`](./api-refs/api-ref.mdx) | +| OpenAPI Endpoint Reference | Schema-backed endpoint pages generated around `docs/openapi.json`. | [`docs/api-reference/endpoint/`](./api-reference/endpoint/createRoutingRule.mdx) | +| OpenAPI contract | Machine-readable contract consumed by Mintlify and tooling. | [`docs/openapi.json`](./openapi.json) | + +If you need rule examples such as AND, OR, nested AND+OR, `volume_split_priority`, enum arrays, or number-array matching, start with [Advanced Routing Example](./api-refs/routing-advanced-example.mdx). If you need the exact `POST /routing/create` schema and playground metadata, use [Create Routing Rule](./api-reference/endpoint/createRoutingRule.mdx). + +## Access classes + +| Class | Routes | Authentication | +| --- | --- | --- | +| Public | `GET /health`, `GET /health/ready`, `GET /health/diagnostics`, `POST /auth/signup`, `POST /auth/login` | None | +| Admin bootstrap | `POST /merchant-account/create` | Admin secret | +| Protected | All routing, decision, score update, rule config, API key, merchant read/delete, analytics, audit, config, and authenticated auth routes | `Authorization: Bearer ` or `x-api-key: ` | +| Sandbox | Any Decision Engine route served through `https://sandbox.hyperswitch.io` | Same auth rules plus `x-feature: decision-engine` | + ## Endpoint Families ### Health diff --git a/docs/api-reference/endpoint/activateRoutingRule.mdx b/docs/api-reference/endpoint/activateRoutingRule.mdx index 16c99020..2515bf51 100644 --- a/docs/api-reference/endpoint/activateRoutingRule.mdx +++ b/docs/api-reference/endpoint/activateRoutingRule.mdx @@ -1,4 +1,65 @@ --- title: "Activate Routing Rule" -openapi: "POST /routing/activate" +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." +openapi: "openapi.json POST /routing/activate" --- + +# Activate Routing Rule + +## Use case + +Marks a created routing algorithm as active for the merchant/creator scope. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /routing/activate` +- Parameters: none. +- Body: JSON body with `created_by` and `routing_algorithm_id` or rule identifier returned by `/routing/create`. + +## Example + +### Activate rule + +```bash +curl --location "$BASE_URL/routing/activate" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "created_by": "merchant_demo", + "routing_algorithm_id": "routing_e641380c-6f24-4405-8454-5ae6cbceb7a0" +}' +``` + +## Response + +```json +{ + "message": "routing rule activated", + "routing_algorithm_id": "routing_e641380c-6f24-4405-8454-5ae6cbceb7a0" +} +``` + +## Notes + +- Only one routing algorithm should be active for a given creator scope. +- Activate before calling `/routing/evaluate` from the explorer. + +## Related + +- [Create Routing Rule](./createRoutingRule.mdx) +- [Get Active Routing Rule](./getActiveRoutingRule.mdx) +- [Activate Routing Algorithm](../../api-refs/routing-algorithm-activate.mdx) diff --git a/docs/api-reference/endpoint/analyticsDecisions.mdx b/docs/api-reference/endpoint/analyticsDecisions.mdx index 9921a9e1..8db69114 100644 --- a/docs/api-reference/endpoint/analyticsDecisions.mdx +++ b/docs/api-reference/endpoint/analyticsDecisions.mdx @@ -1,4 +1,102 @@ --- title: "Analytics Decisions" -openapi: "GET /analytics/decisions" +description: "ClickHouse-backed decisions read endpoint." +openapi: "openapi.json GET /analytics/decisions" --- + +# Analytics Decisions + +## Use case + +Returns decision volume time series and routing approach totals for the selected window. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /analytics/decisions` +- Parameters: + - `range` (query, optional, string) + - `start_ms` (query, optional, integer) + - `end_ms` (query, optional, integer) + - `page` (query, optional, integer) + - `page_size` (query, optional, integer) + - `payment_method_type` (query, optional, string) + - `payment_method` (query, optional, string) + - `card_network` (query, optional, string) + - `card_is_in` (query, optional, string) + - `currency` (query, optional, string) + - `country` (query, optional, string) + - `auth_type` (query, optional, string) + - `gateway` (query, optional, string) + - `payment_id` (query, optional, string) + - `request_id` (query, optional, string) + - `route` (query, optional, string) + - `status` (query, optional, string) + - `flow_type` (query, optional, string) + - `routing_approach` (query, optional, string) + - `exclude_routing_approach` (query, optional, string) + - `error_code` (query, optional, string) +- Body: Optional query parameters include `range`, `routing_approach`, `exclude_routing_approach`, `gateway`, and routing dimensions. + +## Example + +### Decision activity + +```bash +curl "$BASE_URL/analytics/decisions?range=1h" \ + --header "$AUTH_HEADER" +``` + +### Exclude debit routing + +```bash +curl "$BASE_URL/analytics/decisions?range=1d&exclude_routing_approach=NTW_BASED_ROUTING" \ + --header "$AUTH_HEADER" +``` + +## Response + +```json +{ + "series": [ + { + "timestamp_ms": 1777136400000, + "gateway": "adyen", + "count": 7 + }, + { + "timestamp_ms": 1777136400000, + "gateway": "stripe", + "count": 3 + } + ], + "totals": { + "SR_SELECTION_V3_ROUTING": 10 + } +} +``` + +## Notes + +- Analytics reads are ClickHouse-backed and merchant-scoped by the authenticated context. +- Use `range=15m|1h|12h|1d|1w` or `start_ms` plus `end_ms` for a custom window. +- Use this for route volume charts; use gateway scores for auth-rate score percentages. + +## Related + +- [Analytics Routing Stats](./analyticsRoutingStats.mdx) +- [Payment Audit](./analyticsPaymentAudit.mdx) +- [Analytics Endpoints](../../api-refs/analytics-endpoints.mdx) diff --git a/docs/api-reference/endpoint/analyticsGatewayScores.mdx b/docs/api-reference/endpoint/analyticsGatewayScores.mdx index 47051d49..8ec51191 100644 --- a/docs/api-reference/endpoint/analyticsGatewayScores.mdx +++ b/docs/api-reference/endpoint/analyticsGatewayScores.mdx @@ -1,4 +1,98 @@ --- title: "Analytics Gateway Scores" -openapi: "GET /analytics/gateway-scores" +description: "ClickHouse-backed gateway scores read endpoint." +openapi: "openapi.json GET /analytics/gateway-scores" --- + +# Analytics Gateway Scores + +## Use case + +Returns connector success-rate score snapshots and time series for auth-rate based routing. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /analytics/gateway-scores` +- Parameters: + - `range` (query, optional, string) + - `start_ms` (query, optional, integer) + - `end_ms` (query, optional, integer) + - `page` (query, optional, integer) + - `page_size` (query, optional, integer) + - `payment_method_type` (query, optional, string) + - `payment_method` (query, optional, string) + - `card_network` (query, optional, string) + - `card_is_in` (query, optional, string) + - `currency` (query, optional, string) + - `country` (query, optional, string) + - `auth_type` (query, optional, string) + - `gateway` (query, optional, string) + - `payment_id` (query, optional, string) + - `request_id` (query, optional, string) + - `route` (query, optional, string) + - `status` (query, optional, string) + - `flow_type` (query, optional, string) + - `routing_approach` (query, optional, string) + - `exclude_routing_approach` (query, optional, string) + - `error_code` (query, optional, string) +- Body: Optional query parameters include `range`, `gateway`, `payment_method_type`, `payment_method`, `country`, and other routing dimensions. + +## Example + +### Gateway score trend + +```bash +curl "$BASE_URL/analytics/gateway-scores?range=1d&gateway=stripe,adyen" \ + --header "$AUTH_HEADER" +``` + +## Response + +```json +{ + "series": [ + { + "timestamp_ms": 1777136400000, + "gateway": "stripe", + "score": 0.829 + }, + { + "timestamp_ms": 1777136400000, + "gateway": "adyen", + "score": 0.831 + } + ], + "latest": [ + { + "gateway": "adyen", + "score": 0.831 + } + ] +} +``` + +## Notes + +- Analytics reads are ClickHouse-backed and merchant-scoped by the authenticated context. +- Use `range=15m|1h|12h|1d|1w` or `start_ms` plus `end_ms` for a custom window. +- This chart is score percentage, not traffic volume. It may look flat when only one score snapshot exists. + +## Related + +- [Update Gateway Score](./updateGatewayScore.mdx) +- [Analytics Overview](./analyticsOverview.mdx) +- [Analytics Endpoints](../../api-refs/analytics-endpoints.mdx) diff --git a/docs/api-reference/endpoint/analyticsLogSummaries.mdx b/docs/api-reference/endpoint/analyticsLogSummaries.mdx index 6b849865..ac97829f 100644 --- a/docs/api-reference/endpoint/analyticsLogSummaries.mdx +++ b/docs/api-reference/endpoint/analyticsLogSummaries.mdx @@ -1,4 +1,94 @@ --- title: "Analytics Log Summaries" -openapi: "GET /analytics/log-summaries" +description: "ClickHouse-backed log summaries read endpoint." +openapi: "openapi.json GET /analytics/log-summaries" --- + +# Analytics Log Summaries + +## Use case + +Returns error aggregates and recent failed event samples for the selected merchant window. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /analytics/log-summaries` +- Parameters: + - `range` (query, optional, string) + - `start_ms` (query, optional, integer) + - `end_ms` (query, optional, integer) + - `page` (query, optional, integer) + - `page_size` (query, optional, integer) + - `payment_method_type` (query, optional, string) + - `payment_method` (query, optional, string) + - `card_network` (query, optional, string) + - `card_is_in` (query, optional, string) + - `currency` (query, optional, string) + - `country` (query, optional, string) + - `auth_type` (query, optional, string) + - `gateway` (query, optional, string) + - `payment_id` (query, optional, string) + - `request_id` (query, optional, string) + - `route` (query, optional, string) + - `status` (query, optional, string) + - `flow_type` (query, optional, string) + - `routing_approach` (query, optional, string) + - `exclude_routing_approach` (query, optional, string) + - `error_code` (query, optional, string) +- Body: Optional query parameters include `range`, `status=failure`, `error_code`, `gateway`, and routing dimensions. + +## Example + +### Failure summaries + +```bash +curl "$BASE_URL/analytics/log-summaries?range=1d&status=failure" \ + --header "$AUTH_HEADER" +``` + +## Response + +```json +{ + "errors": [ + { + "error_code": "processor_declined", + "count": 2, + "latest_at_ms": 1777136400000 + } + ], + "samples": [ + { + "payment_id": "pay_001", + "gateway": "stripe", + "status": "failure" + } + ] +} +``` + +## Notes + +- Analytics reads are ClickHouse-backed and merchant-scoped by the authenticated context. +- Use `range=15m|1h|12h|1d|1w` or `start_ms` plus `end_ms` for a custom window. +- Use this to diagnose failure spikes before opening individual audit trails. + +## Related + +- [Payment Audit](./analyticsPaymentAudit.mdx) +- [Analytics Overview](./analyticsOverview.mdx) +- [Analytics Endpoints](../../api-refs/analytics-endpoints.mdx) diff --git a/docs/api-reference/endpoint/analyticsOverview.mdx b/docs/api-reference/endpoint/analyticsOverview.mdx index 7be84792..43d91067 100644 --- a/docs/api-reference/endpoint/analyticsOverview.mdx +++ b/docs/api-reference/endpoint/analyticsOverview.mdx @@ -1,4 +1,90 @@ --- title: "Analytics Overview" -openapi: "GET /analytics/overview" +description: "ClickHouse-backed overview read endpoint." +openapi: "openapi.json GET /analytics/overview" --- + +# Analytics Overview + +## Use case + +Returns summary metrics for the dashboard overview: request volume, gateway share, setup status, and recent activity. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /analytics/overview` +- Parameters: + - `range` (query, optional, string) + - `start_ms` (query, optional, integer) + - `end_ms` (query, optional, integer) + - `page` (query, optional, integer) + - `page_size` (query, optional, integer) + - `payment_method_type` (query, optional, string) + - `payment_method` (query, optional, string) + - `card_network` (query, optional, string) + - `card_is_in` (query, optional, string) + - `currency` (query, optional, string) + - `country` (query, optional, string) + - `auth_type` (query, optional, string) + - `gateway` (query, optional, string) + - `payment_id` (query, optional, string) + - `request_id` (query, optional, string) + - `route` (query, optional, string) + - `status` (query, optional, string) + - `flow_type` (query, optional, string) + - `routing_approach` (query, optional, string) + - `exclude_routing_approach` (query, optional, string) + - `error_code` (query, optional, string) +- Body: Optional query parameters include `range`, `start_ms`, and `end_ms`. + +## Example + +### Overview last day + +```bash +curl "$BASE_URL/analytics/overview?range=1d" \ + --header "$AUTH_HEADER" +``` + +## Response + +```json +{ + "range": "1d", + "request_count": 42, + "top_gateway": "adyen", + "gateway_share": [ + { + "gateway": "adyen", + "count": 22, + "share": 52.4 + } + ] +} +``` + +## Notes + +- Analytics reads are ClickHouse-backed and merchant-scoped by the authenticated context. +- Use `range=15m|1h|12h|1d|1w` or `start_ms` plus `end_ms` for a custom window. +- Use this for high-level status, not detailed payment debugging. + +## Related + +- [Analytics Routing Stats](./analyticsRoutingStats.mdx) +- [Payment Audit](./analyticsPaymentAudit.mdx) +- [Analytics Endpoints](../../api-refs/analytics-endpoints.mdx) diff --git a/docs/api-reference/endpoint/analyticsPaymentAudit.mdx b/docs/api-reference/endpoint/analyticsPaymentAudit.mdx index 3a2aa756..06dbc2a0 100644 --- a/docs/api-reference/endpoint/analyticsPaymentAudit.mdx +++ b/docs/api-reference/endpoint/analyticsPaymentAudit.mdx @@ -1,4 +1,120 @@ --- -title: "Analytics Payment Audit" -openapi: "GET /analytics/payment-audit" +title: "Payment Audit" +description: "ClickHouse-backed payment audit read endpoint." +openapi: "openapi.json GET /analytics/payment-audit" --- + +# Payment Audit + +## Use case + +Searches payment decision trails and returns matching payments plus event timelines for audit inspection. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /analytics/payment-audit` +- Parameters: + - `range` (query, optional, string) + - `start_ms` (query, optional, integer) + - `end_ms` (query, optional, integer) + - `page` (query, optional, integer) + - `page_size` (query, optional, integer) + - `payment_method_type` (query, optional, string) + - `payment_method` (query, optional, string) + - `card_network` (query, optional, string) + - `card_is_in` (query, optional, string) + - `currency` (query, optional, string) + - `country` (query, optional, string) + - `auth_type` (query, optional, string) + - `gateway` (query, optional, string) + - `payment_id` (query, optional, string) + - `request_id` (query, optional, string) + - `route` (query, optional, string) + - `status` (query, optional, string) + - `flow_type` (query, optional, string) + - `routing_approach` (query, optional, string) + - `exclude_routing_approach` (query, optional, string) + - `error_code` (query, optional, string) +- Body: Optional query parameters include `range`, `page`, `page_size`, `payment_id`, `gateway`, `status`, `route`, `flow_type`, `routing_approach`, `exclude_routing_approach`, and `error_code`. Use `payment_id` for exact lookup; request IDs are event-level identifiers and may not map to payment summary search in every flow. + +## Example + +### Audit list + +```bash +curl "$BASE_URL/analytics/payment-audit?range=1d&page=1&page_size=10" \ + --header "$AUTH_HEADER" +``` + +### Exact payment lookup + +```bash +curl "$BASE_URL/analytics/payment-audit?range=1d&payment_id=pay_sr_001" \ + --header "$AUTH_HEADER" +``` + +### Debit routing audit + +```bash +curl "$BASE_URL/analytics/payment-audit?range=1d&routing_approach=NTW_BASED_ROUTING" \ + --header "$AUTH_HEADER" +``` + +## Response + +```json +{ + "summary": { + "matching_payments": 1, + "failures": 0, + "active_gateways": [ + "stripe" + ] + }, + "payments": [ + { + "payment_id": "pay_sr_001", + "merchant_id": "merchant_demo", + "latest_status": "success", + "gateways": [ + "stripe" + ] + } + ], + "timeline": [ + { + "event_stage": "gateway_decided", + "route": "decide_gateway", + "gateway": "stripe", + "status": "success" + } + ] +} +``` + +## Notes + +- Analytics reads are ClickHouse-backed and merchant-scoped by the authenticated context. +- Use `range=15m|1h|12h|1d|1w` or `start_ms` plus `end_ms` for a custom window. +- Use `payment_id` as the primary search key in the dashboard. +- Use `exclude_routing_approach=NTW_BASED_ROUTING` to hide debit routing from auth-rate based audit mode. + +## Related + +- [Preview Trace](./analyticsPreviewTrace.mdx) +- [Analytics Log Summaries](./analyticsLogSummaries.mdx) +- [Analytics Endpoints](../../api-refs/analytics-endpoints.mdx) diff --git a/docs/api-reference/endpoint/analyticsPreviewTrace.mdx b/docs/api-reference/endpoint/analyticsPreviewTrace.mdx index 5f993a71..a2e96865 100644 --- a/docs/api-reference/endpoint/analyticsPreviewTrace.mdx +++ b/docs/api-reference/endpoint/analyticsPreviewTrace.mdx @@ -1,4 +1,104 @@ --- -title: "Analytics Preview Trace" -openapi: "GET /analytics/preview-trace" +title: "Preview Trace" +description: "ClickHouse-backed rule preview trace read endpoint." +openapi: "openapi.json GET /analytics/preview-trace" --- + +# Preview Trace + +## Use case + +Returns rule/volume decision traces captured from `/routing/evaluate`. The route name remains `/analytics/preview-trace` for transport compatibility even when the UI labels these as decisions. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /analytics/preview-trace` +- Parameters: + - `range` (query, optional, string) + - `start_ms` (query, optional, integer) + - `end_ms` (query, optional, integer) + - `page` (query, optional, integer) + - `page_size` (query, optional, integer) + - `payment_method_type` (query, optional, string) + - `payment_method` (query, optional, string) + - `card_network` (query, optional, string) + - `card_is_in` (query, optional, string) + - `currency` (query, optional, string) + - `country` (query, optional, string) + - `auth_type` (query, optional, string) + - `gateway` (query, optional, string) + - `payment_id` (query, optional, string) + - `request_id` (query, optional, string) + - `route` (query, optional, string) + - `status` (query, optional, string) + - `flow_type` (query, optional, string) + - `routing_approach` (query, optional, string) + - `exclude_routing_approach` (query, optional, string) + - `error_code` (query, optional, string) +- Body: Optional query parameters include `range`, `page`, `page_size`, `payment_id`, `gateway`, `status`, and `route=routing_evaluate`. + +## Example + +### Rule decision traces + +```bash +curl "$BASE_URL/analytics/preview-trace?range=1d&page=1&page_size=10&route=routing_evaluate" \ + --header "$AUTH_HEADER" +``` + +### Open one decision trace + +```bash +curl "$BASE_URL/analytics/preview-trace?range=1d&payment_id=volume_decision_001" \ + --header "$AUTH_HEADER" +``` + +## Response + +```json +{ + "items": [ + { + "payment_id": "volume_decision_001", + "route": "routing_evaluate", + "gateway": "stripe", + "status": "success", + "events": 1 + } + ], + "timeline": [ + { + "event_stage": "rule_evaluated", + "gateway": "stripe", + "status": "success" + } + ] +} +``` + +## Notes + +- Analytics reads are ClickHouse-backed and merchant-scoped by the authenticated context. +- Use `range=15m|1h|12h|1d|1w` or `start_ms` plus `end_ms` for a custom window. +- Freshly inserted ClickHouse events can take a short moment to become queryable. +- This endpoint is used for rule/volume decision inspection, not auth-rate transaction scoring. + +## Related + +- [Evaluate Routing Rule](./evaluateRoutingRule.mdx) +- [Payment Audit](./analyticsPaymentAudit.mdx) +- [Analytics Endpoints](../../api-refs/analytics-endpoints.mdx) diff --git a/docs/api-reference/endpoint/analyticsRoutingStats.mdx b/docs/api-reference/endpoint/analyticsRoutingStats.mdx index 5365ce5d..74adeed5 100644 --- a/docs/api-reference/endpoint/analyticsRoutingStats.mdx +++ b/docs/api-reference/endpoint/analyticsRoutingStats.mdx @@ -1,4 +1,101 @@ --- title: "Analytics Routing Stats" -openapi: "GET /analytics/routing-stats" +description: "ClickHouse-backed routing stats read endpoint." +openapi: "openapi.json GET /analytics/routing-stats" --- + +# Analytics Routing Stats + +## Use case + +Returns connector share, rule hits, score filters, and routing-stat chart data for the Analytics page. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /analytics/routing-stats` +- Parameters: + - `range` (query, optional, string) + - `start_ms` (query, optional, integer) + - `end_ms` (query, optional, integer) + - `page` (query, optional, integer) + - `page_size` (query, optional, integer) + - `payment_method_type` (query, optional, string) + - `payment_method` (query, optional, string) + - `card_network` (query, optional, string) + - `card_is_in` (query, optional, string) + - `currency` (query, optional, string) + - `country` (query, optional, string) + - `auth_type` (query, optional, string) + - `gateway` (query, optional, string) + - `payment_id` (query, optional, string) + - `request_id` (query, optional, string) + - `route` (query, optional, string) + - `status` (query, optional, string) + - `flow_type` (query, optional, string) + - `routing_approach` (query, optional, string) + - `exclude_routing_approach` (query, optional, string) + - `error_code` (query, optional, string) +- Body: Optional query parameters include `range`, `gateway`, `payment_method_type`, `payment_method`, `country`, and `routing_approach`. + +## Example + +### Routing stats + +```bash +curl "$BASE_URL/analytics/routing-stats?range=1d&payment_method_type=CARD" \ + --header "$AUTH_HEADER" +``` + +## Response + +```json +{ + "gateway_share": [ + { + "gateway": "adyen", + "count": 7, + "share": 70.0 + }, + { + "gateway": "stripe", + "count": 3, + "share": 30.0 + } + ], + "filter_options": { + "payment_method_type": [ + "CARD" + ], + "payment_method": [ + "CREDIT", + "DEBIT" + ] + } +} +``` + +## Notes + +- Analytics reads are ClickHouse-backed and merchant-scoped by the authenticated context. +- Use `range=15m|1h|12h|1d|1w` or `start_ms` plus `end_ms` for a custom window. +- The dashboard uses this for both auth-rate based analytics and rule/volume decision activity. + +## Related + +- [Analytics Decisions](./analyticsDecisions.mdx) +- [Analytics Gateway Scores](./analyticsGatewayScores.mdx) +- [Analytics Endpoints](../../api-refs/analytics-endpoints.mdx) diff --git a/docs/api-reference/endpoint/configSrDimension.mdx b/docs/api-reference/endpoint/configSrDimension.mdx index 1cea6ad4..bec91c7d 100644 --- a/docs/api-reference/endpoint/configSrDimension.mdx +++ b/docs/api-reference/endpoint/configSrDimension.mdx @@ -1,4 +1,67 @@ --- title: "Configure SR Dimensions" -openapi: "POST /config-sr-dimension" +description: "Configure success-rate routing dimensions." +openapi: "openapi.json POST /config-sr-dimension" --- + +# Configure SR Dimensions + +## Use case + +Configures success-rate routing dimensions used for score lookup and aggregation. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /config-sr-dimension` +- Parameters: none. +- Body: JSON body with merchant and selected dimension levels. + +## Example + +### Configure SR dimensions + +```bash +curl --location "$BASE_URL/config-sr-dimension" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchant_id": "merchant_demo", + "payment_method_type": "CARD", + "payment_method": "CREDIT", + "auth_type": "THREE_DS" +}' +``` + +## Response + +```json +{ + "merchant_id": "merchant_demo", + "message": "SR dimension configured" +} +``` + +## Notes + +- Use only dimensions supported by `/config/routing-keys`. +- Changing dimensions affects how future score snapshots are grouped. + +## Related + +- [Get Routing Config](./getRoutingConfig.mdx) +- [Analytics Gateway Scores](./analyticsGatewayScores.mdx) +- [Config Endpoints](../../api-refs/config-endpoints.mdx) diff --git a/docs/api-reference/endpoint/createApiKey.mdx b/docs/api-reference/endpoint/createApiKey.mdx index 0f70dcd5..4466beb8 100644 --- a/docs/api-reference/endpoint/createApiKey.mdx +++ b/docs/api-reference/endpoint/createApiKey.mdx @@ -1,4 +1,67 @@ --- title: "Create API Key" -openapi: "POST /api-key/create" +description: "Create a service-to-service API key for a merchant." +openapi: "openapi.json POST /api-key/create" --- + +# Create API Key + +## Use case + +Creates an API key for server-to-server access to protected Decision Engine routes. + +## Authentication + +Dashboard protected. Send `Authorization: Bearer `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /api-key/create` +- Parameters: none. +- Body: JSON body with `merchant_id`, optional `name`, and optional expiry metadata. + +## Example + +### Create API key + +```bash +curl --location "$BASE_URL/api-key/create" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchant_id": "merchant_demo", + "name": "local-smoke-key" +}' +``` + +## Response + +```json +{ + "key_id": "key_123", + "api_key": "DE_live_xxx", + "merchant_id": "merchant_demo", + "name": "local-smoke-key" +} +``` + +## Notes + +- The raw API key is usually returned only once. Store it securely. +- Use `x-api-key: ` as `AUTH_HEADER` for backend-to-backend examples. + +## Related + +- [List API Keys](./listApiKeys.mdx) +- [Revoke API Key](./revokeApiKey.mdx) +- [Decide Gateway](./decideGateway.mdx) diff --git a/docs/api-reference/endpoint/createMerchant.mdx b/docs/api-reference/endpoint/createMerchant.mdx index 65411968..7d30a947 100644 --- a/docs/api-reference/endpoint/createMerchant.mdx +++ b/docs/api-reference/endpoint/createMerchant.mdx @@ -1,4 +1,66 @@ --- title: "Create Merchant" -openapi: "POST /merchant-account/create" +description: "Register a new merchant account. The merchant ID is the primary identifier used in all subsequent routing and scoring calls." +openapi: "openapi.json POST /merchant-account/create" --- + +# Create Merchant + +## Use case + +Creates a merchant account record used by routing, analytics, and account-level flags. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /merchant-account/create` +- Parameters: none. +- Body: JSON body with merchant identity fields. Keep `merchant_id` stable because it scopes analytics and routing config. + +## Example + +### Create merchant + +```bash +curl --location "$BASE_URL/merchant-account/create" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchant_id": "merchant_demo", + "merchant_name": "Demo Merchant" +}' +``` + +## Response + +```json +{ + "merchant_id": "merchant_demo", + "merchant_name": "Demo Merchant", + "created_at": "2026-04-26T00:00:00Z" +} +``` + +## Notes + +- Dashboard onboarding usually wraps this flow. +- Create the merchant before attaching routing algorithms or API keys. + +## Related + +- [Get Merchant](./getMerchant.mdx) +- [Delete Merchant](./deleteMerchant.mdx) +- [Update Merchant Debit Routing](./updateMerchantDebitRouting.mdx) diff --git a/docs/api-reference/endpoint/createRoutingRule.mdx b/docs/api-reference/endpoint/createRoutingRule.mdx index 353ee9fc..72c92495 100644 --- a/docs/api-reference/endpoint/createRoutingRule.mdx +++ b/docs/api-reference/endpoint/createRoutingRule.mdx @@ -1,4 +1,285 @@ --- title: "Create Routing Rule" -openapi: "POST /routing/create" +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." +openapi: "openapi.json POST /routing/create" --- + +# Create Routing Rule + +## Use case + +Creates a Euclid routing algorithm for a merchant. Use this for rule-based routing, priority routing, single connector routing, and volume split routing. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /routing/create` +- Parameters: none. +- Body: JSON body with `name`, `created_by`, `algorithm_for`, and `algorithm`. `algorithm.type` controls the shape of `algorithm.data`. + +## Example + +### Priority rule + +```bash +curl --location "$BASE_URL/routing/create" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "priority rule", + "created_by": "merchant_demo", + "description": "Try stripe before adyen", + "algorithm_for": "payment", + "algorithm": { + "type": "priority", + "data": [ + { "gateway_name": "stripe", "gateway_id": "mca_stripe" }, + { "gateway_name": "adyen", "gateway_id": "mca_adyen" } + ] + } +}' +``` + +### Single connector + +```bash +curl --location "$BASE_URL/routing/create" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "single connector rule", + "created_by": "merchant_demo", + "algorithm_for": "payment", + "algorithm": { + "type": "single", + "data": { "gateway_name": "stripe", "gateway_id": "mca_stripe" } + } +}' +``` + +### Volume split + +```bash +curl --location "$BASE_URL/routing/create" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "volume split rule", + "created_by": "merchant_demo", + "algorithm_for": "payment", + "algorithm": { + "type": "volume_split", + "data": [ + { "split": 70, "output": { "gateway_name": "stripe", "gateway_id": "mca_stripe" } }, + { "split": 30, "output": { "gateway_name": "adyen", "gateway_id": "mca_adyen" } } + ] + } +}' +``` + +### Advanced rule tree + +```bash +curl --location "$BASE_URL/routing/create" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "metadata rule", + "created_by": "merchant_demo", + "description": "Route Visa BIN 424242 to a priority list", + "algorithm_for": "payment", + "algorithm": { + "type": "advanced", + "data": { + "globals": {}, + "default_selection": { + "priority": [{ "gateway_name": "stripe", "gateway_id": "mca_stripe" }] + }, + "rules": [{ + "name": "visa bin rule", + "routing_type": "priority", + "output": { "priority": [{ "gateway_name": "adyen", "gateway_id": "mca_adyen" }] }, + "statements": [{ + "condition": [{ + "lhs": "card_bin", + "comparison": "equal", + "value": { "type": "str_value", "value": "424242" }, + "metadata": {} + }], + "nested": null + }] + }], + "metadata": {} + } + } +}' +``` + +### Advanced AND rule + +In `advanced` routing, conditions inside the same `condition` array are evaluated as an AND group. Add this rule object inside `algorithm.data.rules`. + +```json +{ + "name": "high_value_netherlands_rule", + "routing_type": "volume_split", + "output": { + "volume_split": [ + { "split": 60, "output": { "gateway_name": "hdfc", "gateway_id": "mca_hdfc" } }, + { "split": 40, "output": { "gateway_name": "instamojo", "gateway_id": "mca_instamojo" } } + ] + }, + "statements": [ + { + "condition": [ + { + "lhs": "amount", + "comparison": "greater_than", + "value": { "type": "number", "value": 100 }, + "metadata": {} + }, + { + "lhs": "billing_country", + "comparison": "equal", + "value": { "type": "enum_variant", "value": "Netherlands" }, + "metadata": {} + } + ], + "nested": null + } + ] +} +``` + +### Advanced OR rule + +Use multiple `statements` when any one branch can trigger the rule. This behaves like OR across statements. + +```json +{ + "name": "card_or_high_value_rule", + "routing_type": "priority", + "output": { + "priority": [ + { "gateway_name": "stripe", "gateway_id": "mca_stripe" }, + { "gateway_name": "adyen", "gateway_id": "mca_adyen" } + ] + }, + "statements": [ + { + "condition": [ + { + "lhs": "payment_method_type", + "comparison": "equal", + "value": { "type": "enum_variant", "value": "CARD" }, + "metadata": {} + } + ], + "nested": null + }, + { + "condition": [ + { + "lhs": "amount", + "comparison": "greater_than", + "value": { "type": "number", "value": 5000 }, + "metadata": {} + } + ], + "nested": null + } + ] +} +``` + +### Advanced nested AND + OR rule + +Use `nested` when a parent condition must match first, and then one of multiple nested branches should match. + +```json +{ + "name": "nested_card_rule", + "routing_type": "priority", + "output": { + "priority": [ + { "gateway_name": "bankofamerica", "gateway_id": "mca_bankofamerica" }, + { "gateway_name": "gigadat", "gateway_id": "mca_gigadat" } + ] + }, + "statements": [ + { + "condition": [ + { + "lhs": "payment_method_type", + "comparison": "equal", + "value": { "type": "enum_variant", "value": "CARD" }, + "metadata": {} + } + ], + "nested": [ + { + "condition": [ + { + "lhs": "card_bin", + "comparison": "equal", + "value": { "type": "str_value", "value": "424242" }, + "metadata": {} + } + ], + "nested": null + }, + { + "condition": [ + { + "lhs": "card_network", + "comparison": "equal", + "value": { "type": "enum_variant", "value": "Visa" }, + "metadata": {} + } + ], + "nested": null + } + ] + } + ] +} +``` + +For more advanced rule examples, including `volume_split_priority`, `enum_variant_array`, `number_array`, and `number_comparison_array`, see [Advanced Routing Example](../../api-refs/routing-advanced-example.mdx). + +## Response + +```json +{ + "rule_id": "routing_e641380c-6f24-4405-8454-5ae6cbceb7a0", + "name": "priority rule", + "created_at": "2026-04-26 10:00:00", + "modified_at": "2026-04-26 10:00:00" +} +``` + +## Notes + +- Creating a rule does not make it active. Call `/routing/activate` after creation. +- For volume split, split percentages should add up to 100. + +## Related + +- [Activate Routing Rule](./activateRoutingRule.mdx) +- [Evaluate Routing Rule](./evaluateRoutingRule.mdx) +- [Advanced Routing Example](../../api-refs/routing-advanced-example.mdx) +- [Priority Routing](../../api-refs/routing-priority-example.mdx) +- [Volume Split Routing](../../api-refs/routing-volume-split-example.mdx) diff --git a/docs/api-reference/endpoint/createRuleConfig.mdx b/docs/api-reference/endpoint/createRuleConfig.mdx index 08b4b20c..295efb4c 100644 --- a/docs/api-reference/endpoint/createRuleConfig.mdx +++ b/docs/api-reference/endpoint/createRuleConfig.mdx @@ -1,4 +1,95 @@ --- title: "Create Rule Config" -openapi: "POST /rule/create" +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." +openapi: "openapi.json POST /rule/create" --- + +# Create Rule Config + +## Use case + +Creates service-level scoring configuration for success-rate or elimination behaviour. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /rule/create` +- Parameters: none. +- Body: JSON body with `merchant_id` and tagged `config`. Supported `config.type` values include `successRate` and `elimination`. + +## Example + +### Create success-rate config + +```bash +curl --location "$BASE_URL/rule/create" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchant_id": "merchant_demo", + "config": { + "type": "successRate", + "data": { + "enabled": true, + "min_aggregates_size": 5, + "default_success_rate": 0.8, + "specificity_level": "merchant" + } + } +}' +``` + +### Create elimination config + +```bash +curl --location "$BASE_URL/rule/create" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchant_id": "merchant_demo", + "config": { + "type": "elimination", + "data": { + "enabled": true, + "bucket_size": 20, + "threshold": 0.25, + "gateway_error_codes": ["processor_declined"] + } + } +}' +``` + +## Response + +```json +{ + "merchant_id": "merchant_demo", + "config_type": "successRate", + "message": "rule config created" +} +``` + +## Notes + +- This is not Euclid rule creation. Use `/routing/create` for routing algorithms. +- Success-rate config affects auth-rate based routing and score snapshots. + +## Related + +- [Get Rule Config](./getRuleConfig.mdx) +- [Update Rule Config](./updateRuleConfig.mdx) +- [Create Success-Rate Config](../../api-refs/success-rate-config-create.mdx) +- [Create Elimination Config](../../api-refs/elimination-config-create.mdx) diff --git a/docs/api-reference/endpoint/decideGateway.mdx b/docs/api-reference/endpoint/decideGateway.mdx index d954c5fb..63eaa0a2 100644 --- a/docs/api-reference/endpoint/decideGateway.mdx +++ b/docs/api-reference/endpoint/decideGateway.mdx @@ -1,4 +1,171 @@ --- title: "Decide Gateway" -openapi: "POST /decide-gateway" +description: "Core routing decision API. Given a payment context and a list of eligible gateways, returns the optimal gateway to route to." +openapi: "openapi.json POST /decide-gateway" --- + +# Decide Gateway + +## Use case + +Runs the core gateway decision flow for a payment. The same endpoint supports auth-rate routing, priority-list routing, debit/network routing, and network+SR hybrid routing. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /decide-gateway` +- Parameters: none. +- Body: JSON body with `merchantId`, `paymentInfo`, `eligibleGatewayList`, and `rankingAlgorithm`. `rankingAlgorithm` must be one of `SR_BASED_ROUTING`, `PL_BASED_ROUTING`, `NTW_BASED_ROUTING`, or `NTW_SR_HYBRID_ROUTING`. + +## Example + +### SR based routing + +```bash +curl --location "$BASE_URL/decide-gateway" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchantId": "merchant_demo", + "eligibleGatewayList": ["stripe", "adyen", "checkout"], + "rankingAlgorithm": "SR_BASED_ROUTING", + "eliminationEnabled": true, + "paymentInfo": { + "paymentId": "pay_sr_001", + "amount": 1000, + "currency": "USD", + "country": "US", + "paymentType": "ORDER_PAYMENT", + "paymentMethodType": "CARD", + "paymentMethod": "CREDIT", + "authType": "THREE_DS", + "cardIsin": "424242" + } +}' +``` + +### Priority-list routing + +```bash +curl --location "$BASE_URL/decide-gateway" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchantId": "merchant_demo", + "eligibleGatewayList": ["stripe", "adyen", "checkout"], + "rankingAlgorithm": "PL_BASED_ROUTING", + "eliminationEnabled": true, + "paymentInfo": { + "paymentId": "pay_pl_001", + "amount": 1000, + "currency": "USD", + "country": "US", + "paymentType": "ORDER_PAYMENT", + "paymentMethodType": "CARD", + "paymentMethod": "CREDIT", + "authType": "THREE_DS", + "cardIsin": "424242" + } +}' +``` + +### Debit/network routing + +```bash +curl --location "$BASE_URL/decide-gateway" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchantId": "merchant_demo", + "eligibleGatewayList": ["stripe", "adyen"], + "rankingAlgorithm": "NTW_BASED_ROUTING", + "paymentInfo": { + "paymentId": "pay_debit_001", + "amount": 1000, + "currency": "USD", + "country": "US", + "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\":{\"card_type\":\"debit\",\"issuer_country\":\"US\",\"is_regulated\":false,\"regulated_name\":null,\"card_networks\":[\"VISA\",\"NYCE\",\"PULSE\",\"STAR\"]}}" + } +}' +``` + +### Network + SR hybrid routing + +```bash +curl --location "$BASE_URL/decide-gateway" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchantId": "merchant_demo", + "eligibleGatewayList": ["stripe", "adyen"], + "rankingAlgorithm": "NTW_SR_HYBRID_ROUTING", + "paymentInfo": { + "paymentId": "pay_hybrid_001", + "amount": 1000, + "currency": "USD", + "country": "US", + "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\":{\"card_type\":\"debit\",\"issuer_country\":\"US\",\"is_regulated\":false,\"regulated_name\":null,\"card_networks\":[\"VISA\",\"NYCE\",\"PULSE\",\"STAR\"]}}" + } +}' +``` + +## Response + +```json +{ + "decided_gateway": "stripe", + "gateway_priority_map": { + "stripe": 0.94, + "adyen": 0.91 + }, + "routing_approach": "SR_SELECTION_V3_ROUTING", + "gateway_before_evaluation": "stripe", + "debit_routing_output": { + "co_badged_card_networks_info": [ + { + "network": "NYCE", + "saving_percentage": 1.2 + } + ], + "issuer_country": "US", + "is_regulated": false, + "card_type": "debit" + }, + "is_rust_based_decider": true +} +``` + +## Notes + +- Use backend enum strings exactly; camelCase values such as `NtwBasedRouting` are invalid. +- Debit routing requires the merchant debit-routing flag to be enabled and debit metadata encoded as a JSON string in `paymentInfo.metadata`. +- A successful call emits analytics/audit events asynchronously. + +## Related + +- [Decide Gateway: SR Based Routing](../../api-refs/decide-gateway-sr-based.mdx) +- [Decide Gateway: PL Based Routing](../../api-refs/decide-gateway-pl-based.mdx) +- [Decide Gateway: Debit Routing](../../api-refs/decide-gateway-debit-routing.mdx) +- [Decide Gateway: Hybrid Routing](../../api-refs/decide-gateway-hybrid-routing.mdx) +- [Update Gateway Score](./updateGatewayScore.mdx) diff --git a/docs/api-reference/endpoint/deleteMerchant.mdx b/docs/api-reference/endpoint/deleteMerchant.mdx index 934ba803..6f5f1938 100644 --- a/docs/api-reference/endpoint/deleteMerchant.mdx +++ b/docs/api-reference/endpoint/deleteMerchant.mdx @@ -1,4 +1,61 @@ --- title: "Delete Merchant" -openapi: "DELETE /merchant-account/{merchantId}" +description: "Delete a merchant account and all associated routing configuration." +openapi: "openapi.json DELETE /merchant-account/{merchantId}" --- + +# Delete Merchant + +## Use case + +Deletes a merchant account from Decision Engine local state. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `DELETE /merchant-account/{merchantId}` +- Parameters: + - `merchantId` (path, required, string) +- Body: Path parameter `merchantId` is the merchant account ID. + +## Example + +### Delete merchant + +```bash +curl --location "$BASE_URL/merchant-account/merchant_demo" \ + --header "$AUTH_HEADER" \ + --request DELETE +``` + +## Response + +```json +{ + "deleted": true, + "merchant_id": "merchant_demo" +} +``` + +## Notes + +- Do not use this in shared sandbox data unless you are cleaning up your own test merchant. +- Deleting a merchant does not imply external payment processor cleanup. + +## Related + +- [Create Merchant](./createMerchant.mdx) +- [Get Merchant](./getMerchant.mdx) diff --git a/docs/api-reference/endpoint/deleteRuleConfig.mdx b/docs/api-reference/endpoint/deleteRuleConfig.mdx index 64a58043..dde4546a 100644 --- a/docs/api-reference/endpoint/deleteRuleConfig.mdx +++ b/docs/api-reference/endpoint/deleteRuleConfig.mdx @@ -1,4 +1,79 @@ --- title: "Delete Rule Config" -openapi: "POST /rule/delete" +description: "Delete a rule configuration." +openapi: "openapi.json POST /rule/delete" --- + +# Delete Rule Config + +## Use case + +Deletes a service-level success-rate or elimination configuration for a merchant. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /rule/delete` +- Parameters: none. +- Body: JSON body with `merchant_id` and `config.type` to delete. + +## Example + +### Delete success-rate config + +```bash +curl --location "$BASE_URL/rule/delete" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchant_id": "merchant_demo", + "config": { "type": "successRate" } +}' +``` + +### Delete elimination config + +```bash +curl --location "$BASE_URL/rule/delete" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchant_id": "merchant_demo", + "config": { "type": "elimination" } +}' +``` + +## Response + +```json +{ + "merchant_id": "merchant_demo", + "config_type": "successRate", + "deleted": true +} +``` + +## Notes + +- Deleting config makes the dashboard show that surface as not configured. +- Routing may fall back to defaults if config is absent. + +## Related + +- [Create Rule Config](./createRuleConfig.mdx) +- [Get Rule Config](./getRuleConfig.mdx) +- [Delete Success-Rate Config](../../api-refs/success-rate-config-delete.mdx) +- [Delete Elimination Config](../../api-refs/elimination-config-delete.mdx) diff --git a/docs/api-reference/endpoint/evaluateRoutingRule.mdx b/docs/api-reference/endpoint/evaluateRoutingRule.mdx index a6569396..3fcb38e5 100644 --- a/docs/api-reference/endpoint/evaluateRoutingRule.mdx +++ b/docs/api-reference/endpoint/evaluateRoutingRule.mdx @@ -1,4 +1,80 @@ --- title: "Evaluate Routing Rule" -openapi: "POST /routing/evaluate" +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." +openapi: "openapi.json POST /routing/evaluate" --- + +# Evaluate Routing Rule + +## Use case + +Evaluates the active rule-based or volume-split routing algorithm for a payment context. This is a real evaluation endpoint for rule decisions, kept separate from auth-rate transaction scoring. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /routing/evaluate` +- Parameters: none. +- Body: JSON body with `merchantId` and `paymentInfo`. + +## Example + +### Evaluate active rule + +```bash +curl --location "$BASE_URL/routing/evaluate" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchantId": "merchant_demo", + "paymentInfo": { + "paymentId": "rule_decision_001", + "amount": 1000, + "currency": "USD", + "country": "US", + "paymentType": "ORDER_PAYMENT", + "paymentMethodType": "CARD", + "paymentMethod": "CREDIT", + "authType": "THREE_DS", + "cardIsin": "424242" + } +}' +``` + +## Response + +```json +{ + "gateway": "stripe", + "gateways": [ + "stripe", + "adyen" + ], + "routing_approach": "RULE_EVALUATE_DECISION", + "rule_name": "volume_split_rule" +} +``` + +## Notes + +- This endpoint does not call `/update-gateway-score` and does not consume auth-rate score updates. +- Analytics stores these as rule/volume decisions under the `/analytics/preview-trace` transport endpoint. + +## Related + +- [Create Routing Rule](./createRoutingRule.mdx) +- [Preview Trace](./analyticsPreviewTrace.mdx) +- [Evaluate Routing Algorithm](../../api-refs/routing-algorithm-evaluate.mdx) diff --git a/docs/api-reference/endpoint/getActiveRoutingRule.mdx b/docs/api-reference/endpoint/getActiveRoutingRule.mdx index 1619bffc..f6d52628 100644 --- a/docs/api-reference/endpoint/getActiveRoutingRule.mdx +++ b/docs/api-reference/endpoint/getActiveRoutingRule.mdx @@ -1,4 +1,67 @@ --- title: "Get Active Routing Rule" -openapi: "POST /routing/list/active/{created_by}" +description: "Retrieve the currently active routing rule for a merchant." +openapi: "openapi.json POST /routing/list/active/{created_by}" --- + +# Get Active Routing Rule + +## Use case + +Fetches the currently active routing algorithm for a creator/merchant scope. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /routing/list/active/{created_by}` +- Parameters: + - `created_by` (path, required, string) +- Body: Path parameter `created_by`; request body can be `{}`. + +## Example + +### Get active rule + +```bash +curl --location "$BASE_URL/routing/list/active/merchant_demo" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{}' +``` + +## Response + +```json +{ + "rule_id": "routing_e641380c-6f24-4405-8454-5ae6cbceb7a0", + "name": "priority rule", + "active": true, + "algorithm": { + "type": "priority" + } +} +``` + +## Notes + +- The dashboard uses this before volume/rule evaluations. +- A missing active rule means the explorer should ask the operator to configure routing first. + +## Related + +- [List Routing Rules](./listRoutingRules.mdx) +- [Activate Routing Rule](./activateRoutingRule.mdx) +- [List Active Routing Algorithms](../../api-refs/routing-algorithm-list-active.mdx) diff --git a/docs/api-reference/endpoint/getMerchant.mdx b/docs/api-reference/endpoint/getMerchant.mdx index 05ad50f7..e001bfdd 100644 --- a/docs/api-reference/endpoint/getMerchant.mdx +++ b/docs/api-reference/endpoint/getMerchant.mdx @@ -1,4 +1,62 @@ --- title: "Get Merchant" -openapi: "GET /merchant-account/{merchantId}" +description: "Retrieve a merchant account by ID." +openapi: "openapi.json GET /merchant-account/{merchantId}" --- + +# Get Merchant + +## Use case + +Fetches merchant account metadata and current account-level settings. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /merchant-account/{merchantId}` +- Parameters: + - `merchantId` (path, required, string) +- Body: Path parameter `merchantId` is the merchant account ID. + +## Example + +### Get merchant + +```bash +curl "$BASE_URL/merchant-account/merchant_demo" \ + --header "$AUTH_HEADER" +``` + +## Response + +```json +{ + "merchant_id": "merchant_demo", + "merchant_name": "Demo Merchant", + "created_at": "2026-04-26T00:00:00Z" +} +``` + +## Notes + +- A 404 means the merchant has not been created in Decision Engine. +- Use the same merchant ID in routing and analytics calls. + +## Related + +- [Create Merchant](./createMerchant.mdx) +- [Get Merchant Debit Routing](./getMerchantDebitRouting.mdx) +- [List User Merchants](./listUserMerchants.mdx) diff --git a/docs/api-reference/endpoint/getMerchantDebitRouting.mdx b/docs/api-reference/endpoint/getMerchantDebitRouting.mdx index 51c416d0..c6713cdd 100644 --- a/docs/api-reference/endpoint/getMerchantDebitRouting.mdx +++ b/docs/api-reference/endpoint/getMerchantDebitRouting.mdx @@ -1,4 +1,61 @@ --- title: "Get Merchant Debit Routing" -openapi: "GET /merchant-account/{merchantId}/debit-routing" +description: "Return whether debit/network routing is enabled for a merchant. Missing flag configuration is treated as disabled." +openapi: "openapi.json GET /merchant-account/{merchantId}/debit-routing" --- + +# Get Merchant Debit Routing + +## Use case + +Reads whether debit/network routing is enabled for a merchant. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /merchant-account/{merchantId}/debit-routing` +- Parameters: + - `merchantId` (path, required, string) +- Body: Path parameter `merchantId` is the merchant account ID. + +## Example + +### Get debit-routing flag + +```bash +curl "$BASE_URL/merchant-account/merchant_demo/debit-routing" \ + --header "$AUTH_HEADER" +``` + +## Response + +```json +{ + "merchant_id": "merchant_demo", + "debit_routing_enabled": true +} +``` + +## Notes + +- Missing configuration is treated as disabled. +- The Decision Explorer debit-routing tab should check this before calling `NTW_BASED_ROUTING`. + +## Related + +- [Update Merchant Debit Routing](./updateMerchantDebitRouting.mdx) +- [Decide Gateway](./decideGateway.mdx) +- [Merchant Debit Routing](../../api-refs/merchant-debit-routing.mdx) diff --git a/docs/api-reference/endpoint/getRoutingConfig.mdx b/docs/api-reference/endpoint/getRoutingConfig.mdx index 2d5c32ab..900b7af7 100644 --- a/docs/api-reference/endpoint/getRoutingConfig.mdx +++ b/docs/api-reference/endpoint/getRoutingConfig.mdx @@ -1,4 +1,66 @@ --- title: "Get Routing Config" -openapi: "GET /config/routing-keys" +description: "Return rule-builder routing keys and supported values." +openapi: "openapi.json GET /config/routing-keys" --- + +# Get Routing Config + +## Use case + +Returns routing keys/dimensions used by the dashboard to build routing configuration forms. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /config/routing-keys` +- Parameters: none. +- Body: No parameters or request body. + +## Example + +### Get routing keys + +```bash +curl "$BASE_URL/config/routing-keys" \ + --header "$AUTH_HEADER" +``` + +## Response + +```json +{ + "routing_keys": [ + "payment_method_type", + "payment_method", + "card_network", + "currency", + "country", + "auth_type" + ] +} +``` + +## Notes + +- Use this to keep UI selectors aligned with backend-supported routing dimensions. +- The exact set can vary as backend routing attributes evolve. + +## Related + +- [Configure SR Dimensions](./configSrDimension.mdx) +- [Create Routing Rule](./createRoutingRule.mdx) +- [Config Endpoints](../../api-refs/config-endpoints.mdx) diff --git a/docs/api-reference/endpoint/getRuleConfig.mdx b/docs/api-reference/endpoint/getRuleConfig.mdx index f4ed063b..83fd3807 100644 --- a/docs/api-reference/endpoint/getRuleConfig.mdx +++ b/docs/api-reference/endpoint/getRuleConfig.mdx @@ -1,4 +1,84 @@ --- title: "Get Rule Config" -openapi: "POST /rule/get" +description: "Retrieve an existing rule configuration by merchant and type." +openapi: "openapi.json POST /rule/get" --- + +# Get Rule Config + +## Use case + +Fetches a service-level success-rate or elimination configuration for a merchant. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /rule/get` +- Parameters: none. +- Body: JSON body with `merchant_id` and `config.type`. + +## Example + +### Get success-rate config + +```bash +curl --location "$BASE_URL/rule/get" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchant_id": "merchant_demo", + "config": { "type": "successRate" } +}' +``` + +### Get elimination config + +```bash +curl --location "$BASE_URL/rule/get" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchant_id": "merchant_demo", + "config": { "type": "elimination" } +}' +``` + +## Response + +```json +{ + "merchant_id": "merchant_demo", + "config": { + "type": "successRate", + "data": { + "enabled": true, + "default_success_rate": 0.8 + } + } +} +``` + +## Notes + +- A missing config should be treated as not configured in the dashboard. +- Use this to determine overview setup readiness. + +## Related + +- [Create Rule Config](./createRuleConfig.mdx) +- [Update Rule Config](./updateRuleConfig.mdx) +- [Get Success-Rate Config](../../api-refs/success-rate-config-get.mdx) +- [Get Elimination Config](../../api-refs/elimination-config-get.mdx) diff --git a/docs/api-reference/endpoint/healthCheck.mdx b/docs/api-reference/endpoint/healthCheck.mdx index 8f7349b3..6bb980b1 100644 --- a/docs/api-reference/endpoint/healthCheck.mdx +++ b/docs/api-reference/endpoint/healthCheck.mdx @@ -1,4 +1,58 @@ --- title: "Health Check" -openapi: "GET /health" +description: "Service liveness check." +openapi: "openapi.json GET /health" --- + +# Health Check + +## Use case + +Checks whether the HTTP service is reachable. Use this for lightweight uptime checks and local smoke tests. + +## Authentication + +Public. No JWT or API key is required. Sandbox traffic may still include `x-feature: decision-engine` when routed through Hyperswitch. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /health` +- Parameters: none. +- Body: No parameters or request body. + +## Example + +### Health check + +```bash +curl "$BASE_URL/health" +``` + +## Response + +```json +{ + "status": "ok", + "service": "decision-engine" +} +``` + +## Notes + +- This endpoint should not depend on ClickHouse, Redis, or the application database. +- Use `/health/ready` for dependency-aware readiness checks. + +## Related + +- [Health Ready](./healthReady.mdx) +- [Health Diagnostics](./healthDiagnostics.mdx) diff --git a/docs/api-reference/endpoint/healthDiagnostics.mdx b/docs/api-reference/endpoint/healthDiagnostics.mdx index 907c047f..20f21e8b 100644 --- a/docs/api-reference/endpoint/healthDiagnostics.mdx +++ b/docs/api-reference/endpoint/healthDiagnostics.mdx @@ -1,4 +1,61 @@ --- title: "Health Diagnostics" -openapi: "GET /health/diagnostics" +description: "Database diagnostics for local and deployment troubleshooting." +openapi: "openapi.json GET /health/diagnostics" --- + +# Health Diagnostics + +## Use case + +Returns a deeper diagnostic snapshot for operators debugging local or sandbox environments. + +## Authentication + +Public. No JWT or API key is required. Sandbox traffic may still include `x-feature: decision-engine` when routed through Hyperswitch. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /health/diagnostics` +- Parameters: none. +- Body: No parameters or request body. + +## Example + +### Diagnostics + +```bash +curl "$BASE_URL/health/diagnostics" +``` + +## Response + +```json +{ + "service": "decision-engine", + "database": "ok", + "redis": "ok", + "clickhouse": "ok", + "version": "v1.4" +} +``` + +## Notes + +- Diagnostics may expose operational details, so production gateways can restrict access at the edge. +- Use it during setup before testing routing APIs. + +## Related + +- [Health Check](./healthCheck.mdx) +- [Health Ready](./healthReady.mdx) diff --git a/docs/api-reference/endpoint/healthReady.mdx b/docs/api-reference/endpoint/healthReady.mdx index 97e5967f..ef623f1a 100644 --- a/docs/api-reference/endpoint/healthReady.mdx +++ b/docs/api-reference/endpoint/healthReady.mdx @@ -1,4 +1,62 @@ --- title: "Health Ready" -openapi: "GET /health/ready" +description: "Returns Up when the process is ready to serve traffic." +openapi: "openapi.json GET /health/ready" --- + +# Health Ready + +## Use case + +Checks whether the service is ready to receive traffic, including critical dependency checks. + +## Authentication + +Public. No JWT or API key is required. Sandbox traffic may still include `x-feature: decision-engine` when routed through Hyperswitch. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /health/ready` +- Parameters: none. +- Body: No parameters or request body. + +## Example + +### Readiness check + +```bash +curl "$BASE_URL/health/ready" +``` + +## Response + +```json +{ + "ready": true, + "checks": { + "database": "ok", + "redis": "ok", + "clickhouse": "ok" + } +} +``` + +## Notes + +- Use this for container readiness probes. +- A dependency failure should mark readiness unhealthy without changing the basic `/health` response. + +## Related + +- [Health Check](./healthCheck.mdx) +- [Health Diagnostics](./healthDiagnostics.mdx) diff --git a/docs/api-reference/endpoint/hybridRouting.mdx b/docs/api-reference/endpoint/hybridRouting.mdx index 2d852850..af3aad4d 100644 --- a/docs/api-reference/endpoint/hybridRouting.mdx +++ b/docs/api-reference/endpoint/hybridRouting.mdx @@ -1,4 +1,77 @@ --- title: "Hybrid Routing" -openapi: "POST /routing/hybrid" +description: "Evaluate hybrid routing using the active routing rule plus runtime payment context." +openapi: "openapi.json POST /routing/hybrid" --- + +# Hybrid Routing + +## Use case + +Evaluates a routing configuration that combines rule output with runtime gateway scoring. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /routing/hybrid` +- Parameters: none. +- Body: JSON body with merchant/payment context and the routing inputs required by the hybrid route. + +## Example + +### Hybrid routing + +```bash +curl --location "$BASE_URL/routing/hybrid" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchantId": "merchant_demo", + "paymentInfo": { + "paymentId": "hybrid_rule_001", + "amount": 1000, + "currency": "USD", + "paymentType": "ORDER_PAYMENT", + "paymentMethodType": "CARD", + "paymentMethod": "CREDIT" + }, + "eligibleGatewayList": ["stripe", "adyen"] +}' +``` + +## Response + +```json +{ + "decided_gateway": "stripe", + "rule_gateway": "stripe", + "score_context": { + "stripe": 0.94, + "adyen": 0.91 + } +} +``` + +## Notes + +- Use `/decide-gateway` with `NTW_SR_HYBRID_ROUTING` for debit network + SR hybrid decisions. +- Use this route only when the hybrid rule evaluation contract is needed. + +## Related + +- [Evaluate Routing Rule](./evaluateRoutingRule.mdx) +- [Decide Gateway](./decideGateway.mdx) +- [Hybrid Routing](../../api-refs/routing-hybrid.mdx) diff --git a/docs/api-reference/endpoint/legacyDecisionGateway.mdx b/docs/api-reference/endpoint/legacyDecisionGateway.mdx index 0d7916fa..0c4dafd3 100644 --- a/docs/api-reference/endpoint/legacyDecisionGateway.mdx +++ b/docs/api-reference/endpoint/legacyDecisionGateway.mdx @@ -1,4 +1,81 @@ --- title: "Legacy Decision Gateway" -openapi: "POST /decision_gateway" +description: "Legacy compatibility route. New integrations should use /decide-gateway." +openapi: "openapi.json POST /decision_gateway" --- + +# Legacy Decision Gateway + +## Use case + +Compatibility endpoint for older integrations that still call `/decision_gateway`. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /decision_gateway` +- Parameters: none. +- Body: Uses the same decision request shape as `/decide-gateway`. + +## Example + +### Legacy decision call + +```bash +curl --location "$BASE_URL/decision_gateway" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchantId": "merchant_demo", + "eligibleGatewayList": ["stripe", "adyen", "checkout"], + "rankingAlgorithm": "SR_BASED_ROUTING", + "eliminationEnabled": true, + "paymentInfo": { + "paymentId": "pay_legacy_001", + "amount": 1000, + "currency": "USD", + "country": "US", + "paymentType": "ORDER_PAYMENT", + "paymentMethodType": "CARD", + "paymentMethod": "CREDIT", + "authType": "THREE_DS", + "cardIsin": "424242" + } +}' +``` + +## Response + +```json +{ + "decided_gateway": "stripe", + "gateway_priority_map": { + "stripe": 0.94, + "adyen": 0.91 + }, + "routing_approach": "SR_SELECTION_V3_ROUTING" +} +``` + +## Notes + +- New integrations should use `/decide-gateway`. +- Keep this route for migration compatibility only. + +## Related + +- [Decide Gateway](./decideGateway.mdx) +- [Legacy Decision Gateway](../../api-refs/decision-gateway-legacy.mdx) diff --git a/docs/api-reference/endpoint/legacyUpdateScore.mdx b/docs/api-reference/endpoint/legacyUpdateScore.mdx index e82456e2..63ff5ad6 100644 --- a/docs/api-reference/endpoint/legacyUpdateScore.mdx +++ b/docs/api-reference/endpoint/legacyUpdateScore.mdx @@ -1,4 +1,66 @@ --- title: "Legacy Update Score" -openapi: "POST /update-score" +description: "Legacy compatibility route. New integrations should use /update-gateway-score." +openapi: "openapi.json POST /update-score" --- + +# Legacy Update Score + +## Use case + +Compatibility endpoint for older integrations that still call `/update-score`. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /update-score` +- Parameters: none. +- Body: Uses the same score update payload as `/update-gateway-score`. + +## Example + +### Legacy update score + +```bash +curl --location "$BASE_URL/update-score" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchantId": "merchant_demo", + "paymentId": "pay_sr_001", + "gateway": "stripe", + "status": "success" +}' +``` + +## Response + +```json +{ + "status": "success", + "message": "score updated" +} +``` + +## Notes + +- New integrations should use `/update-gateway-score`. +- Keep this route only for older clients. + +## Related + +- [Update Gateway Score](./updateGatewayScore.mdx) +- [Legacy Update Score](../../api-refs/update-score-legacy.mdx) diff --git a/docs/api-reference/endpoint/listApiKeys.mdx b/docs/api-reference/endpoint/listApiKeys.mdx index 8daeb1d6..1d012383 100644 --- a/docs/api-reference/endpoint/listApiKeys.mdx +++ b/docs/api-reference/endpoint/listApiKeys.mdx @@ -1,4 +1,66 @@ --- title: "List API Keys" -openapi: "GET /api-key/list/{merchant_id}" +description: "List active and revoked API keys for a merchant." +openapi: "openapi.json GET /api-key/list/{merchant_id}" --- + +# List API Keys + +## Use case + +Lists API keys registered for a merchant without exposing raw key secrets. + +## Authentication + +Dashboard protected. Send `Authorization: Bearer `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /api-key/list/{merchant_id}` +- Parameters: + - `merchant_id` (path, required, string) +- Body: Path parameter `merchant_id` identifies the merchant account. + +## Example + +### List keys + +```bash +curl "$BASE_URL/api-key/list/merchant_demo" \ + --header "$AUTH_HEADER" +``` + +## Response + +```json +{ + "keys": [ + { + "key_id": "key_123", + "merchant_id": "merchant_demo", + "name": "local-smoke-key", + "created_at": "2026-04-26T00:00:00Z" + } + ] +} +``` + +## Notes + +- Use this for key management screens. +- Revoke by `key_id`, not by raw key value. + +## Related + +- [Create API Key](./createApiKey.mdx) +- [Revoke API Key](./revokeApiKey.mdx) diff --git a/docs/api-reference/endpoint/listRoutingRules.mdx b/docs/api-reference/endpoint/listRoutingRules.mdx index 85bf0926..7af57dab 100644 --- a/docs/api-reference/endpoint/listRoutingRules.mdx +++ b/docs/api-reference/endpoint/listRoutingRules.mdx @@ -1,4 +1,69 @@ --- title: "List Routing Rules" -openapi: "POST /routing/list/{created_by}" +description: "List all routing rules for a merchant." +openapi: "openapi.json POST /routing/list/{created_by}" --- + +# List Routing Rules + +## Use case + +Lists routing algorithms created by a merchant/operator scope. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /routing/list/{created_by}` +- Parameters: + - `created_by` (path, required, string) +- Body: Path parameter `created_by`; optional request body can be `{}`. + +## Example + +### List rules + +```bash +curl --location "$BASE_URL/routing/list/merchant_demo" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{}' +``` + +## Response + +```json +{ + "rules": [ + { + "rule_id": "routing_e641380c-6f24-4405-8454-5ae6cbceb7a0", + "name": "priority rule", + "active": true, + "algorithm_for": "payment" + } + ] +} +``` + +## Notes + +- Use this to render routing history and select which rule to activate. +- The route is POST for compatibility even though it behaves like a list read. + +## Related + +- [Get Active Routing Rule](./getActiveRoutingRule.mdx) +- [Activate Routing Rule](./activateRoutingRule.mdx) +- [List Routing Algorithms](../../api-refs/routing-algorithm-list.mdx) diff --git a/docs/api-reference/endpoint/listUserMerchants.mdx b/docs/api-reference/endpoint/listUserMerchants.mdx index 49b87305..d8042f1f 100644 --- a/docs/api-reference/endpoint/listUserMerchants.mdx +++ b/docs/api-reference/endpoint/listUserMerchants.mdx @@ -1,4 +1,68 @@ --- title: "List User Merchants" -openapi: "GET /auth/merchants" +description: "Return merchants available to the current user." +openapi: "openapi.json GET /auth/merchants" --- + +# List User Merchants + +## Use case + +Lists merchant workspaces available to the authenticated dashboard operator. + +## Authentication + +Dashboard protected. Send `Authorization: Bearer `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /auth/merchants` +- Parameters: none. +- Body: No parameters or request body. + +## Example + +### List merchants + +```bash +curl "$BASE_URL/auth/merchants" \ + --header "$AUTH_HEADER" +``` + +## Response + +```json +{ + "merchants": [ + { + "merchant_id": "merchant_demo", + "merchant_name": "Demo Merchant" + }, + { + "merchant_id": "merchant_sbx", + "merchant_name": "Sandbox Merchant" + } + ] +} +``` + +## Notes + +- Use this to populate the dashboard merchant switcher. +- The active merchant is still controlled by the auth token/session context. + +## Related + +- [Switch Merchant](./switchMerchant.mdx) +- [Onboard Merchant](./onboardMerchant.mdx) +- [Current User](./me.mdx) diff --git a/docs/api-reference/endpoint/login.mdx b/docs/api-reference/endpoint/login.mdx index dbac99cd..0488aced 100644 --- a/docs/api-reference/endpoint/login.mdx +++ b/docs/api-reference/endpoint/login.mdx @@ -1,4 +1,73 @@ --- title: "Login" -openapi: "POST /auth/login" +description: "Create a dashboard JWT session." +openapi: "openapi.json POST /auth/login" --- + +# Login + +## Use case + +Authenticates a dashboard operator and returns a JWT used by the dashboard and protected API examples. + +## Authentication + +Public. No JWT or API key is required. Sandbox traffic may still include `x-feature: decision-engine` when routed through Hyperswitch. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /auth/login` +- Parameters: none. +- Body: JSON body with `email` and `password`. + +## Example + +### Login + +```bash +curl --location "$BASE_URL/auth/login" \ + --header "Content-Type: application/json" \ + --data '{ + "email": "operator@example.com", + "password": "StrongPass#123" +}' +``` + +## Response + +```json +{ + "token": "eyJ...", + "user_id": "user_123", + "email": "operator@example.com", + "merchant_id": "merchant_demo", + "role": "admin", + "merchants": [ + { + "merchant_id": "merchant_demo", + "merchant_name": "Demo Merchant" + } + ] +} +``` + +## Notes + +- After login, export `AUTH_HEADER="Authorization: Bearer "` for protected examples. +- If the token expires, call login again rather than retrying failed protected calls blindly. + +## Related + +- [Signup](./signup.mdx) +- [Current User](./me.mdx) +- [List User Merchants](./listUserMerchants.mdx) diff --git a/docs/api-reference/endpoint/logout.mdx b/docs/api-reference/endpoint/logout.mdx index bc91ebf9..fe435ed3 100644 --- a/docs/api-reference/endpoint/logout.mdx +++ b/docs/api-reference/endpoint/logout.mdx @@ -1,4 +1,60 @@ --- title: "Logout" -openapi: "POST /auth/logout" +description: "Revoke the current dashboard JWT." +openapi: "openapi.json POST /auth/logout" --- + +# Logout + +## Use case + +Invalidates the current dashboard session on the client/server auth boundary. + +## Authentication + +Dashboard protected. Send `Authorization: Bearer `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /auth/logout` +- Parameters: none. +- Body: No request body. + +## Example + +### Logout + +```bash +curl --location "$BASE_URL/auth/logout" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{}' +``` + +## Response + +```json +{ + "message": "Logged out successfully" +} +``` + +## Notes + +- Clear local dashboard session state after a successful logout. +- API keys are not affected by dashboard logout. + +## Related + +- [Login](./login.mdx) +- [Current User](./me.mdx) diff --git a/docs/api-reference/endpoint/me.mdx b/docs/api-reference/endpoint/me.mdx index 556c2579..c56b717c 100644 --- a/docs/api-reference/endpoint/me.mdx +++ b/docs/api-reference/endpoint/me.mdx @@ -1,4 +1,62 @@ --- title: "Current User" -openapi: "GET /auth/me" +description: "Return current authenticated user and merchant context." +openapi: "openapi.json GET /auth/me" --- + +# Current User + +## Use case + +Returns the current authenticated dashboard operator and selected merchant context. + +## Authentication + +Dashboard protected. Send `Authorization: Bearer `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `GET /auth/me` +- Parameters: none. +- Body: No parameters or request body. + +## Example + +### Current user + +```bash +curl "$BASE_URL/auth/me" \ + --header "$AUTH_HEADER" +``` + +## Response + +```json +{ + "user_id": "user_123", + "email": "operator@example.com", + "merchant_id": "merchant_demo", + "role": "admin" +} +``` + +## Notes + +- Use this after refresh to restore the authenticated dashboard state. +- A 401 means the dashboard should return to login. + +## Related + +- [Login](./login.mdx) +- [List User Merchants](./listUserMerchants.mdx) +- [Switch Merchant](./switchMerchant.mdx) diff --git a/docs/api-reference/endpoint/onboardMerchant.mdx b/docs/api-reference/endpoint/onboardMerchant.mdx index 2b272885..b98311d3 100644 --- a/docs/api-reference/endpoint/onboardMerchant.mdx +++ b/docs/api-reference/endpoint/onboardMerchant.mdx @@ -1,4 +1,65 @@ --- title: "Onboard Merchant" -openapi: "POST /onboarding/merchant" +description: "Create and attach a merchant to the current operator user." +openapi: "openapi.json POST /onboarding/merchant" --- + +# Onboard Merchant + +## Use case + +Creates a merchant workspace from the authenticated dashboard flow. + +## Authentication + +Dashboard protected. Send `Authorization: Bearer `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /onboarding/merchant` +- Parameters: none. +- Body: JSON body with `merchant_name`. + +## Example + +### Onboard merchant + +```bash +curl --location "$BASE_URL/onboarding/merchant" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchant_name": "Demo Merchant" +}' +``` + +## Response + +```json +{ + "merchant_id": "merchant_demo", + "merchant_name": "Demo Merchant", + "created": true +} +``` + +## Notes + +- This is the dashboard onboarding route. Service integrations can use `/merchant-account/create` directly. +- After onboarding, switch into the merchant before configuring routing. + +## Related + +- [Switch Merchant](./switchMerchant.mdx) +- [Create Merchant](./createMerchant.mdx) +- [Get Merchant](./getMerchant.mdx) diff --git a/docs/api-reference/endpoint/revokeApiKey.mdx b/docs/api-reference/endpoint/revokeApiKey.mdx index 61281d7a..dbf27f1c 100644 --- a/docs/api-reference/endpoint/revokeApiKey.mdx +++ b/docs/api-reference/endpoint/revokeApiKey.mdx @@ -1,4 +1,61 @@ --- title: "Revoke API Key" -openapi: "DELETE /api-key/{key_id}" +description: "Mark an API key inactive and clear its Redis cache entry." +openapi: "openapi.json DELETE /api-key/{key_id}" --- + +# Revoke API Key + +## Use case + +Revokes a server-to-server API key so it can no longer call protected routes. + +## Authentication + +Dashboard protected. Send `Authorization: Bearer `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `DELETE /api-key/{key_id}` +- Parameters: + - `key_id` (path, required, string) +- Body: Path parameter `key_id` identifies the key to revoke. + +## Example + +### Revoke key + +```bash +curl --location "$BASE_URL/api-key/key_123" \ + --header "$AUTH_HEADER" \ + --request DELETE +``` + +## Response + +```json +{ + "deleted": true, + "key_id": "key_123" +} +``` + +## Notes + +- Existing requests using the revoked key should receive authorization failures after revocation propagates. +- Dashboard JWT sessions are not affected. + +## Related + +- [Create API Key](./createApiKey.mdx) +- [List API Keys](./listApiKeys.mdx) diff --git a/docs/api-reference/endpoint/signup.mdx b/docs/api-reference/endpoint/signup.mdx index 0b114d0f..a9449a17 100644 --- a/docs/api-reference/endpoint/signup.mdx +++ b/docs/api-reference/endpoint/signup.mdx @@ -1,4 +1,74 @@ --- title: "Signup" -openapi: "POST /auth/signup" +description: "Create an operator account. Password must meet dashboard password policy." +openapi: "openapi.json POST /auth/signup" --- + +# Signup + +## Use case + +Creates a dashboard operator account and associates it with the initial merchant workspace. + +## Authentication + +Public. No JWT or API key is required. Sandbox traffic may still include `x-feature: decision-engine` when routed through Hyperswitch. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /auth/signup` +- Parameters: none. +- Body: JSON body with `email`, `password`, and merchant identifier/name depending on the dashboard onboarding flow. Passwords must satisfy the dashboard policy. + +## Example + +### Create account + +```bash +curl --location "$BASE_URL/auth/signup" \ + --header "Content-Type: application/json" \ + --data '{ + "email": "operator@example.com", + "password": "StrongPass#123", + "merchant_id": "merchant_demo" +}' +``` + +## Response + +```json +{ + "token": "eyJ...", + "user_id": "user_123", + "email": "operator@example.com", + "merchant_id": "merchant_demo", + "role": "admin", + "merchants": [ + { + "merchant_id": "merchant_demo", + "merchant_name": "Demo Merchant" + } + ] +} +``` + +## Notes + +- If the email already exists, redirect the user to login rather than creating a duplicate account. +- Use at least 10 characters with uppercase, lowercase, number, and special character. + +## Related + +- [Login](./login.mdx) +- [Onboard Merchant](./onboardMerchant.mdx) +- [Create Merchant](../endpoint/createMerchant.mdx) diff --git a/docs/api-reference/endpoint/switchMerchant.mdx b/docs/api-reference/endpoint/switchMerchant.mdx index 8bc19ed0..e0be33fc 100644 --- a/docs/api-reference/endpoint/switchMerchant.mdx +++ b/docs/api-reference/endpoint/switchMerchant.mdx @@ -1,4 +1,65 @@ --- title: "Switch Merchant" -openapi: "POST /auth/switch-merchant" +description: "Switch the current dashboard merchant context." +openapi: "openapi.json POST /auth/switch-merchant" --- + +# Switch Merchant + +## Use case + +Switches the dashboard operator to a different merchant workspace and returns updated session context. + +## Authentication + +Dashboard protected. Send `Authorization: Bearer `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /auth/switch-merchant` +- Parameters: none. +- Body: JSON body with `merchant_id` from `/auth/merchants`. + +## Example + +### Switch merchant + +```bash +curl --location "$BASE_URL/auth/switch-merchant" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchant_id": "merchant_demo" +}' +``` + +## Response + +```json +{ + "token": "eyJ...", + "merchant_id": "merchant_demo", + "merchant_name": "Demo Merchant" +} +``` + +## Notes + +- Refresh stored dashboard auth context with the returned token/session data. +- Use this before reading merchant-scoped analytics. + +## Related + +- [List User Merchants](./listUserMerchants.mdx) +- [Current User](./me.mdx) +- [Analytics Overview](../endpoint/analyticsOverview.mdx) diff --git a/docs/api-reference/endpoint/updateGatewayScore.mdx b/docs/api-reference/endpoint/updateGatewayScore.mdx index d6b5a1e9..0effeab7 100644 --- a/docs/api-reference/endpoint/updateGatewayScore.mdx +++ b/docs/api-reference/endpoint/updateGatewayScore.mdx @@ -1,4 +1,73 @@ --- title: "Update Gateway Score" -openapi: "POST /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." +openapi: "openapi.json POST /update-gateway-score" --- + +# Update Gateway Score + +## Use case + +Records the observed transaction outcome for a previously selected gateway so auth-rate analytics can learn from real payment results. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /update-gateway-score` +- Parameters: none. +- Body: JSON body should include merchant/payment identity, selected gateway, status, and latency/outcome details expected by the score updater. + +## Example + +### Update gateway score + +```bash +curl --location "$BASE_URL/update-gateway-score" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchantId": "merchant_demo", + "paymentId": "pay_sr_001", + "gateway": "stripe", + "status": "success", + "amount": 1000, + "currency": "USD", + "paymentMethodType": "CARD", + "paymentMethod": "CREDIT", + "authType": "THREE_DS", + "latency": 120 +}' +``` + +## Response + +```json +{ + "status": "success", + "message": "gateway score updated" +} +``` + +## Notes + +- Do not call this after `NTW_BASED_ROUTING` just to record the selected debit network; debit audit comes from `/decide-gateway` analytics. +- Call it after payment authorization completes, not before. + +## Related + +- [Decide Gateway](./decideGateway.mdx) +- [Analytics Gateway Scores](./analyticsGatewayScores.mdx) +- [Update Gateway Score](../../api-refs/update-gateway-score.mdx) diff --git a/docs/api-reference/endpoint/updateMerchantDebitRouting.mdx b/docs/api-reference/endpoint/updateMerchantDebitRouting.mdx index a81f6277..40937083 100644 --- a/docs/api-reference/endpoint/updateMerchantDebitRouting.mdx +++ b/docs/api-reference/endpoint/updateMerchantDebitRouting.mdx @@ -1,4 +1,76 @@ --- title: "Update Merchant Debit Routing" -openapi: "POST /merchant-account/{merchantId}/debit-routing" +description: "Enable or disable runtime debit/network routing for a merchant." +openapi: "openapi.json POST /merchant-account/{merchantId}/debit-routing" --- + +# Update Merchant Debit Routing + +## Use case + +Enables or disables runtime debit/network routing for a merchant. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /merchant-account/{merchantId}/debit-routing` +- Parameters: + - `merchantId` (path, required, string) +- Body: Path parameter `merchantId`; JSON body with `enabled` boolean. + +## Example + +### Enable debit routing + +```bash +curl --location "$BASE_URL/merchant-account/merchant_demo/debit-routing" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "enabled": true +}' +``` + +### Disable debit routing + +```bash +curl --location "$BASE_URL/merchant-account/merchant_demo/debit-routing" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "enabled": false +}' +``` + +## Response + +```json +{ + "merchant_id": "merchant_demo", + "debit_routing_enabled": true +} +``` + +## Notes + +- If disabled, `NTW_BASED_ROUTING` and `NTW_SR_HYBRID_ROUTING` calls should fail with a clear debit-routing-not-enabled error. +- This endpoint toggles the feature flag only; detailed fee/config editing is not exposed by the dashboard yet. + +## Related + +- [Get Merchant Debit Routing](./getMerchantDebitRouting.mdx) +- [Decide Gateway](./decideGateway.mdx) +- [Decide Gateway: Debit Routing](../../api-refs/decide-gateway-debit-routing.mdx) diff --git a/docs/api-reference/endpoint/updateRuleConfig.mdx b/docs/api-reference/endpoint/updateRuleConfig.mdx index 5fa04701..4591eb7f 100644 --- a/docs/api-reference/endpoint/updateRuleConfig.mdx +++ b/docs/api-reference/endpoint/updateRuleConfig.mdx @@ -1,4 +1,95 @@ --- title: "Update Rule Config" -openapi: "POST /rule/update" +description: "Update an existing rule configuration." +openapi: "openapi.json POST /rule/update" --- + +# Update Rule Config + +## Use case + +Updates a merchant scoring configuration for success-rate or elimination. + +## Authentication + +Protected. Send either `Authorization: Bearer ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. + +For local development, start with: + +```bash +export BASE_URL=http://localhost:8080 +export AUTH_HEADER="Authorization: Bearer " +# Sandbox only: +# export BASE_URL=https://sandbox.hyperswitch.io +# export FEATURE_HEADER="x-feature: decision-engine" +``` + +## Request + +- Method and path: `POST /rule/update` +- Parameters: none. +- Body: JSON body with `merchant_id` and full replacement `config` payload. + +## Example + +### Update success-rate config + +```bash +curl --location "$BASE_URL/rule/update" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchant_id": "merchant_demo", + "config": { + "type": "successRate", + "data": { + "enabled": true, + "min_aggregates_size": 5, + "default_success_rate": 0.82, + "specificity_level": "merchant" + } + } +}' +``` + +### Update elimination config + +```bash +curl --location "$BASE_URL/rule/update" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchant_id": "merchant_demo", + "config": { + "type": "elimination", + "data": { + "enabled": true, + "bucket_size": 20, + "threshold": 0.30, + "gateway_error_codes": ["processor_declined"] + } + } +}' +``` + +## Response + +```json +{ + "merchant_id": "merchant_demo", + "config_type": "successRate", + "message": "rule config updated" +} +``` + +## Notes + +- Send the full desired config, not only changed fields. +- Changes affect future routing decisions. + +## Related + +- [Get Rule Config](./getRuleConfig.mdx) +- [Delete Rule Config](./deleteRuleConfig.mdx) +- [Update Success-Rate Config](../../api-refs/success-rate-config-update.mdx) +- [Update Elimination Config](../../api-refs/elimination-config-update.mdx) diff --git a/docs/api-reference1.md b/docs/api-reference1.md deleted file mode 100644 index d1823f93..00000000 --- a/docs/api-reference1.md +++ /dev/null @@ -1,8 +0,0 @@ -# API Reference Moved - -The API reference has moved to the canonical pages: - -- [API Overview](api-reference.md) -- [API Examples](api-refs/api-ref.mdx) - -Use the overview for schema-backed endpoint pages and the examples page for curl-first flows. diff --git a/docs/api-refs/analytics-endpoints.mdx b/docs/api-refs/analytics-endpoints.mdx index b74f8bfe..2c81a4f4 100644 --- a/docs/api-refs/analytics-endpoints.mdx +++ b/docs/api-refs/analytics-endpoints.mdx @@ -5,38 +5,77 @@ description: "Curl examples for ClickHouse-backed analytics, charts, payment aud # Analytics Endpoints -Analytics routes derive the merchant from the authenticated user/API key context. Common query parameters: +Analytics routes derive the merchant from the authenticated user/API key context and read from the analytics store. Use these endpoints for dashboard charts, payment audit, rule/volume decision inspection, and debit-routing audit. + +Common query parameters: | Parameter | Values | | --- | --- | | `range` | `15m`, `1h`, `12h`, `1d`, `1w` | | `start_ms`, `end_ms` | custom epoch-millisecond window | | `page`, `page_size` | paginated list endpoints | -| `gateway`, `status`, `route`, `flow_type`, `routing_approach` | filters | +| `gateway`, `status`, `route`, `flow_type`, `routing_approach`, `exclude_routing_approach` | filters | +| `payment_id` | exact payment lookup for audit and trace views | +| `error_code` | failure filtering | ## Overview +High-level dashboard summary for the selected merchant and time window. + ```bash curl "$BASE_URL/analytics/overview?range=1d" \ --header "$AUTH_HEADER" ``` +```json +{ + "request_count": 42, + "top_gateway": "adyen", + "gateway_share": [ + { "gateway": "adyen", "count": 22, "share": 52.4 } + ] +} +``` + ## Gateway Scores +Auth-rate score snapshots and connector success-rate trend. + ```bash curl "$BASE_URL/analytics/gateway-scores?range=1d&gateway=stripe,adyen" \ --header "$AUTH_HEADER" ``` +```json +{ + "latest": [ + { "gateway": "adyen", "score": 0.831 }, + { "gateway": "stripe", "score": 0.829 } + ], + "series": [ + { "timestamp_ms": 1777136400000, "gateway": "adyen", "score": 0.831 } + ] +} +``` + ## Decisions +Decision volume by connector and routing approach. + ```bash curl "$BASE_URL/analytics/decisions?range=1d" \ --header "$AUTH_HEADER" ``` +```bash +curl "$BASE_URL/analytics/decisions?range=1d&exclude_routing_approach=NTW_BASED_ROUTING" \ + --header "$AUTH_HEADER" +``` + ## Routing Stats +Connector share, rule hits, routing filter options, and chart data. + ```bash curl "$BASE_URL/analytics/routing-stats?range=1d&payment_method_type=CARD" \ --header "$AUTH_HEADER" @@ -44,6 +83,8 @@ curl "$BASE_URL/analytics/routing-stats?range=1d&payment_method_type=CARD" \ ## Log Summaries +Failure aggregates and recent error samples. + ```bash curl "$BASE_URL/analytics/log-summaries?range=1d&status=failure" \ --header "$AUTH_HEADER" @@ -51,21 +92,67 @@ curl "$BASE_URL/analytics/log-summaries?range=1d&status=failure" \ ## Payment Audit +Payment-level trail search. Prefer `payment_id` for exact lookup. + ```bash curl "$BASE_URL/analytics/payment-audit?range=1d&page=1&page_size=12&payment_id=pay_001" \ --header "$AUTH_HEADER" ``` +```bash +curl "$BASE_URL/analytics/payment-audit?range=1d&gateway=stripe&status=success&page=1&page_size=10" \ + --header "$AUTH_HEADER" +``` + +```json +{ + "summary": { + "matching_payments": 1, + "failures": 0, + "active_gateways": ["stripe"] + }, + "payments": [ + { + "payment_id": "pay_001", + "latest_status": "success", + "gateways": ["stripe"] + } + ], + "timeline": [ + { + "route": "decide_gateway", + "event_stage": "gateway_decided", + "gateway": "stripe", + "status": "success" + } + ] +} +``` + ## Preview Trace +Rule/volume decisions captured from `/routing/evaluate`. The transport route remains `/analytics/preview-trace` even when the UI labels these as decisions. + ```bash curl "$BASE_URL/analytics/preview-trace?range=1d&page=1&page_size=12&route=routing_evaluate" \ --header "$AUTH_HEADER" ``` +```bash +curl "$BASE_URL/analytics/preview-trace?range=1d&payment_id=volume_decision_001" \ + --header "$AUTH_HEADER" +``` + ## Debit Routing Audit ```bash curl "$BASE_URL/analytics/payment-audit?range=1d&routing_approach=NTW_BASED_ROUTING" \ --header "$AUTH_HEADER" ``` + +## Notes + +- Use `range` for preset windows and `start_ms`/`end_ms` for custom windows. +- Use `page` and `page_size` on list-heavy views such as payment audit and preview trace. +- Use `exclude_routing_approach=NTW_BASED_ROUTING` when auth-rate audit should hide debit-routing decisions. +- Freshly inserted analytics events may take a short moment to appear because writes are asynchronous. diff --git a/docs/api-refs/api-ref.mdx b/docs/api-refs/api-ref.mdx index ec0c81de..582b2658 100644 --- a/docs/api-refs/api-ref.mdx +++ b/docs/api-refs/api-ref.mdx @@ -5,7 +5,28 @@ description: "Human-friendly Decision Engine API map with curl examples for ever # API Examples -Use this page as the route map for local smoke tests, dashboard integration, and sandbox debugging. For schema-level details, use [API Overview](/api-reference) and the OpenAPI-backed endpoint pages. +Use this page as the main route map for local smoke tests, dashboard integration, and sandbox debugging. It groups the APIs by the flows an operator usually performs: create merchant, create API key, configure routing, run transactions, send feedback, inspect analytics, and audit decisions. For schema-level details, use [API Overview](../api-reference.md) and the OpenAPI-backed endpoint pages. + +## Which API docs should I use? + +There are two API documentation surfaces: + +| Surface | Location | Purpose | +| --- | --- | --- | +| API Examples | `docs/api-refs/*.mdx` | Human-facing curl examples, complete flows, request variants, and practical payloads. Start here when testing or integrating. | +| OpenAPI Endpoint Reference | `docs/api-reference/endpoint/*.mdx` | One page per OpenAPI operation, backed by `docs/openapi.json` for schema/playground rendering. Use this when checking exact request/response schema. | + +The advanced AND, OR, nested, and value-variant routing examples live in [Advanced rule tree](./routing-advanced-example.mdx). The `/routing/create` OpenAPI page also includes a shorter version for quick schema-page lookup. + +## Route access model + +| Access class | Routes | Required headers | +| --- | --- | --- | +| Public health | `GET /health`, `GET /health/ready`, `GET /health/diagnostics` | None | +| Public auth entrypoint | `POST /auth/signup`, `POST /auth/login` | None | +| Admin bootstrap | `POST /merchant-account/create` | Admin secret as configured for the deployment | +| Protected operator/API-key APIs | Auth session, API keys, merchant reads/deletes, routing, rule config, decision, score update, config, analytics, and audit routes | `Authorization: Bearer ` or `x-api-key: ` | +| Sandbox Hyperswitch routing | Same protected/public route rules, routed through `https://sandbox.hyperswitch.io` | Add `x-feature: decision-engine` | ## Environment @@ -32,65 +53,74 @@ curl "$BASE_URL/analytics/overview?range=1d" \ --header "$FEATURE_HEADER" ``` -## Contents +## Main Contents ### Health -- [Health, readiness, and diagnostics](/api-refs/health-check): `GET /health`, `GET /health/ready`, `GET /health/diagnostics` +- [Health, readiness, and diagnostics](./health-check.mdx): service liveness, dependency readiness, and local diagnostics with `GET /health`, `GET /health/ready`, and `GET /health/diagnostics`. + +### Auth And Onboarding + +- [Auth and onboarding](./auth-and-onboarding.mdx): dashboard operator signup, login, logout, current user, merchant list, merchant switch, and dashboard merchant onboarding. + +### Merchant CRUD + +- [Create merchant account](./merchant-account-create.mdx): create the merchant record used by routing, API keys, and analytics. +- [Get merchant account](./merchant-account-get.mdx): inspect the merchant account and setup state. +- [Delete merchant account](./merchant-account-delete.mdx): remove a test merchant from Decision Engine local state. + +### API Key CRUD + +- [API keys](./api-keys.mdx): create, list, and revoke server-to-server API keys with `POST /api-key/create`, `GET /api-key/list/:merchant_id`, and `DELETE /api-key/:key_id`. + +### Rule-Based Routing CRUD And Lifecycle + +- [Create routing algorithm](./routing-algorithm-create.mdx): create `single`, `priority`, `volume_split`, and `advanced` routing algorithms. +- [Single connector](./routing-single-connector-example.mdx): always return one configured connector. +- [Priority list](./routing-priority-example.mdx): return connectors in a fixed ordered priority. +- [Volume split](./routing-volume-split-example.mdx): distribute decisions across connectors by configured percentages. +- [Advanced rule tree](./routing-advanced-example.mdx): AND, OR, nested AND+OR rules plus value variants such as enum arrays and number ranges. +- [Activate routing algorithm](./routing-algorithm-activate.mdx): make a created algorithm active for a merchant. +- [List routing algorithms](./routing-algorithm-list.mdx): list created algorithms. +- [List active routing algorithms](./routing-algorithm-list-active.mdx): read the active algorithm. +- [Evaluate routing algorithm](./routing-algorithm-evaluate.mdx): run a rule/volume decision through `/routing/evaluate`. +- [Hybrid routing evaluation](./routing-hybrid.mdx): evaluate the hybrid routing surface when rule output must be combined with runtime scoring. + +There is no public deactivate route in the current API contract. To change active behavior, create or select another algorithm and call `/routing/activate`. -### Auth, onboarding, and API keys +### Rule Config CRUD -- [Auth and onboarding](/api-refs/auth-and-onboarding): `POST /auth/signup`, `POST /auth/login`, `POST /auth/logout`, `GET /auth/me`, `GET /auth/merchants`, `POST /auth/switch-merchant`, `POST /onboarding/merchant` -- [API keys](/api-refs/api-keys): `POST /api-key/create`, `GET /api-key/list/:merchant_id`, `DELETE /api-key/:key_id` +- [Create success-rate config](./success-rate-config-create.mdx), [get](./success-rate-config-get.mdx), [update](./success-rate-config-update.mdx), and [delete](./success-rate-config-delete.mdx): manage auth-rate scoring config. +- [Create elimination config](./elimination-config-create.mdx), [get](./elimination-config-get.mdx), [update](./elimination-config-update.mdx), and [delete](./elimination-config-delete.mdx): manage downtime/elimination config. -### Merchant account +### Decide Gateway Transactions -- [Create merchant account](/api-refs/merchant-account-create): `POST /merchant-account/create` -- [Get merchant account](/api-refs/merchant-account-get): `GET /merchant-account/:merchant-id` -- [Delete merchant account](/api-refs/merchant-account-delete): `DELETE /merchant-account/:merchant-id` -- [Debit-routing merchant flag](/api-refs/merchant-debit-routing): `GET|POST /merchant-account/:merchant-id/debit-routing` +- [SR-based routing](./decide-gateway-sr-based.mdx): transact with `SR_BASED_ROUTING`. +- [Priority-list routing](./decide-gateway-pl-based.mdx): transact with `PL_BASED_ROUTING`. +- [Debit/network routing](./decide-gateway-debit-routing.mdx): transact with `NTW_BASED_ROUTING`. +- [Network + SR hybrid routing](./decide-gateway-hybrid-routing.mdx): transact with `NTW_SR_HYBRID_ROUTING`. -### Gateway decisions +### Update Gateway Score -- [SR-based routing](/api-refs/decide-gateway-sr-based): `POST /decide-gateway` with `SR_BASED_ROUTING` -- [Priority-list routing](/api-refs/decide-gateway-pl-based): `POST /decide-gateway` with `PL_BASED_ROUTING` -- [Debit/network routing](/api-refs/decide-gateway-debit-routing): `POST /decide-gateway` with `NTW_BASED_ROUTING` -- [Network + SR hybrid routing](/api-refs/decide-gateway-hybrid-routing): `POST /decide-gateway` with `NTW_SR_HYBRID_ROUTING` -- [Legacy decision endpoint](/api-refs/decision-gateway-legacy): `POST /decision_gateway` -- [Update gateway score](/api-refs/update-gateway-score): `POST /update-gateway-score` -- [Legacy update score](/api-refs/update-score-legacy): `POST /update-score` +- [Update gateway score](./update-gateway-score.mdx): send post-authorization feedback to update auth-rate analytics and scoring. -### Routing rules +### Debit Routing -- [Create routing algorithm](/api-refs/routing-algorithm-create): `POST /routing/create` -- [Evaluate routing algorithm](/api-refs/routing-algorithm-evaluate): `POST /routing/evaluate` -- [Hybrid routing evaluation](/api-refs/routing-hybrid): `POST /routing/hybrid` -- [List routing algorithms](/api-refs/routing-algorithm-list): `POST /routing/list/:created_by` -- [List active routing algorithms](/api-refs/routing-algorithm-list-active): `POST /routing/list/active/:created_by` -- [Activate routing algorithm](/api-refs/routing-algorithm-activate): `POST /routing/activate` +- [Debit-routing merchant flag](./merchant-debit-routing.mdx): read, enable, and disable merchant-level debit routing. +- [Debit/network routing transaction](./decide-gateway-debit-routing.mdx): run `/decide-gateway` with debit metadata after the flag is enabled. -### Routing algorithm shapes +### Config -- [Single connector](/api-refs/routing-single-connector-example): `algorithm.type = single` -- [Priority list](/api-refs/routing-priority-example): `algorithm.type = priority` -- [Volume split](/api-refs/routing-volume-split-example): `algorithm.type = volume_split` -- [Advanced rule tree](/api-refs/routing-advanced-example): `algorithm.type = advanced` +- [Routing config endpoints](./config-endpoints.mdx): get supported routing keys and configure SR dimensions. -### Rule configuration +### Analytics And Audit -- [Create success-rate config](/api-refs/success-rate-config-create): `POST /rule/create` -- [Get success-rate config](/api-refs/success-rate-config-get): `POST /rule/get` -- [Update success-rate config](/api-refs/success-rate-config-update): `POST /rule/update` -- [Delete success-rate config](/api-refs/success-rate-config-delete): `POST /rule/delete` -- [Create elimination config](/api-refs/elimination-config-create): `POST /rule/create` -- [Get elimination config](/api-refs/elimination-config-get): `POST /rule/get` -- [Update elimination config](/api-refs/elimination-config-update): `POST /rule/update` -- [Delete elimination config](/api-refs/elimination-config-delete): `POST /rule/delete` +- [Analytics endpoints](./analytics-endpoints.mdx): overview, gateway scores, decisions, routing stats, logs, payment audit, preview trace, pagination, filters, and debit-routing audit. -### Config and analytics +### Compatibility -- [Routing config endpoints](/api-refs/config-endpoints): `GET /config/routing-keys`, `POST /config-sr-dimension` -- [Analytics endpoints](/api-refs/analytics-endpoints): `/analytics/overview`, `/analytics/gateway-scores`, `/analytics/decisions`, `/analytics/routing-stats`, `/analytics/log-summaries`, `/analytics/payment-audit`, `/analytics/preview-trace` +- [Legacy decision endpoint](./decision-gateway-legacy.mdx): old `/decision_gateway` compatibility route. +- [Legacy update score](./update-score-legacy.mdx): old `/update-score` compatibility route. ## Routing Algorithm Values diff --git a/docs/api-refs/decision-gateway-legacy.mdx b/docs/api-refs/decision-gateway-legacy.mdx index 3f165b7f..9422d47f 100644 --- a/docs/api-refs/decision-gateway-legacy.mdx +++ b/docs/api-refs/decision-gateway-legacy.mdx @@ -5,7 +5,7 @@ description: "Compatibility example for the legacy /decision_gateway route." # Legacy Decision Gateway -`/decision_gateway` is retained for compatibility with older integrations. New integrations should use [`/decide-gateway`](/api-refs/decide-gateway-sr-based). +`/decision_gateway` is retained for compatibility with older integrations. New integrations should use [`/decide-gateway`](./decide-gateway-sr-based.mdx). ```bash curl --location "$BASE_URL/decision_gateway" \ diff --git a/docs/api-refs/merchant-debit-routing.mdx b/docs/api-refs/merchant-debit-routing.mdx index 063c59ab..3b4ec790 100644 --- a/docs/api-refs/merchant-debit-routing.mdx +++ b/docs/api-refs/merchant-debit-routing.mdx @@ -5,7 +5,7 @@ description: "Curl examples for reading and updating the merchant debit-routing # Merchant Debit Routing Flag -Debit/network routing is gated per merchant. Missing config defaults to disabled. +Debit/network routing is gated per merchant. Missing config defaults to disabled. Enable this flag before calling `/decide-gateway` with `NTW_BASED_ROUTING` or `NTW_SR_HYBRID_ROUTING`. ## Read Flag @@ -30,6 +30,13 @@ curl --location "$BASE_URL/merchant-account/merchant_demo/debit-routing" \ --data '{ "enabled": true }' ``` +```json +{ + "merchant_id": "merchant_demo", + "debit_routing_enabled": true +} +``` + ## Disable Flag ```bash @@ -38,3 +45,57 @@ curl --location "$BASE_URL/merchant-account/merchant_demo/debit-routing" \ --header "Content-Type: application/json" \ --data '{ "enabled": false }' ``` + +## Run Debit Routing Transaction + +After enabling the flag, send a debit card transaction through `/decide-gateway`. The debit router expects `paymentInfo.metadata` to be a JSON string containing `merchant_category_code`, `acquirer_country`, and `co_badged_card_data`. + +```bash +curl --location "$BASE_URL/decide-gateway" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "merchantId": "merchant_demo", + "eligibleGatewayList": ["stripe", "adyen"], + "rankingAlgorithm": "NTW_BASED_ROUTING", + "paymentInfo": { + "paymentId": "debit_001", + "amount": 1000, + "currency": "USD", + "country": "US", + "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\":{\"card_type\":\"debit\",\"issuer_country\":\"US\",\"is_regulated\":false,\"regulated_name\":null,\"card_networks\":[\"VISA\",\"NYCE\",\"PULSE\",\"STAR\"]}}" + } + }' +``` + +```json +{ + "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.8 } + ], + "issuer_country": "US", + "is_regulated": false, + "card_type": "debit" + } +} +``` + +## Notes + +- Use backend enum strings: `NTW_BASED_ROUTING` and `NTW_SR_HYBRID_ROUTING`. +- `co_badged_card_data.card_type` must be lowercase `debit` or `credit` inside metadata. +- If the flag is disabled, debit-routing transactions should fail with a debit-routing-not-enabled error. + +## Related + +- [Debit Gateway Transaction](./decide-gateway-debit-routing.mdx) +- [Network + SR Hybrid Routing](./decide-gateway-hybrid-routing.mdx) +- [Payment Audit](./analytics-endpoints.mdx) diff --git a/docs/api-refs/routing-advanced-example.mdx b/docs/api-refs/routing-advanced-example.mdx index 4af0c8e2..4ff198d8 100644 --- a/docs/api-refs/routing-advanced-example.mdx +++ b/docs/api-refs/routing-advanced-example.mdx @@ -1,20 +1,46 @@ --- title: "Advanced Routing Example" -description: "Advanced Euclid rule tree example for /routing/create." +description: "Advanced Euclid rule tree examples for /routing/create, including AND, OR, nested rules, and value variants." --- # Advanced Routing Example -Use `algorithm.type = advanced` when the rule needs conditions, fallback output, and default selection. +Use `algorithm.type = advanced` when a merchant needs conditional rule-based routing instead of a fixed connector order. Advanced rules evaluate payment attributes, choose the first matching rule output, and fall back to `default_selection` when no rule matches. + +## Advanced Program Shape + +```json +{ + "globals": {}, + "default_selection": { + "priority": [ + { "gateway_name": "stripe", "gateway_id": "mca_stripe" } + ] + }, + "rules": [], + "metadata": {} +} +``` + +| Field | Meaning | +| --- | --- | +| `globals` | Optional reusable value sets referenced by `global_ref`. | +| `default_selection` | Fallback `single`, `priority`, `volume_split`, or `volume_split_priority` output. | +| `rules[].routing_type` | Rule output behavior: `priority`, `volume_split`, or `volume_split_priority`. | +| `rules[].output` | Connector output returned when the rule matches. | +| `rules[].statements[].condition` | Conditions inside one statement. All conditions in the same array must match. | +| `rules[].statements[].nested` | Optional nested statements. Parent condition must match and then nested statements are evaluated. | + +## Full Create Request ```bash curl --location "$BASE_URL/routing/create" \ --header "$AUTH_HEADER" \ --header "Content-Type: application/json" \ --data '{ - "name": "card metadata rule", + "name": "advanced card routing", "created_by": "merchant_demo", - "description": "Route Visa card traffic by priority", + "description": "Route Visa card traffic by priority, otherwise fallback to stripe", "algorithm_for": "payment", "algorithm": { "type": "advanced", @@ -22,7 +48,7 @@ curl --location "$BASE_URL/routing/create" \ "globals": {}, "default_selection": { "priority": [ - { "gateway_name": "stripe", "gateway_id": "mca_111" } + { "gateway_name": "stripe", "gateway_id": "mca_stripe" } ] }, "rules": [ @@ -31,8 +57,8 @@ curl --location "$BASE_URL/routing/create" \ "routing_type": "priority", "output": { "priority": [ - { "gateway_name": "adyen", "gateway_id": "mca_112" }, - { "gateway_name": "stripe", "gateway_id": "mca_111" } + { "gateway_name": "adyen", "gateway_id": "mca_adyen" }, + { "gateway_name": "stripe", "gateway_id": "mca_stripe" } ] }, "statements": [ @@ -61,3 +87,267 @@ curl --location "$BASE_URL/routing/create" \ } }' ``` + +## Logic Variants + +### AND Rule + +Use one `condition` array when all conditions must match. + +```json +{ + "name": "high_value_netherlands_rule", + "routing_type": "volume_split", + "output": { + "volume_split": [ + { + "split": 60, + "output": { "gateway_name": "hdfc", "gateway_id": "mca_hdfc" } + }, + { + "split": 40, + "output": { "gateway_name": "instamojo", "gateway_id": "mca_instamojo" } + } + ] + }, + "statements": [ + { + "condition": [ + { + "lhs": "amount", + "comparison": "greater_than", + "value": { "type": "number", "value": 100 }, + "metadata": {} + }, + { + "lhs": "billing_country", + "comparison": "equal", + "value": { "type": "enum_variant", "value": "Netherlands" }, + "metadata": {} + } + ], + "nested": null + } + ] +} +``` + +### OR Rule + +Use multiple statements when any statement can trigger the rule. + +```json +{ + "name": "card_or_high_value_rule", + "routing_type": "priority", + "output": { + "priority": [ + { "gateway_name": "paytm", "gateway_id": "mca_paytm" }, + { "gateway_name": "adyen", "gateway_id": "mca_adyen" } + ] + }, + "statements": [ + { + "condition": [ + { + "lhs": "payment_method_type", + "comparison": "equal", + "value": { "type": "enum_variant", "value": "CARD" }, + "metadata": {} + } + ], + "nested": null + }, + { + "condition": [ + { + "lhs": "amount", + "comparison": "greater_than", + "value": { "type": "number", "value": 100 }, + "metadata": {} + } + ], + "nested": null + } + ] +} +``` + +### Nested AND + OR Rule + +Use `nested` when a parent condition must match and then one nested branch can match. + +```json +{ + "name": "amount_and_card_network_or_country_rule", + "routing_type": "priority", + "output": { + "priority": [ + { "gateway_name": "rbl", "gateway_id": "mca_rbl" }, + { "gateway_name": "instamojo", "gateway_id": "mca_instamojo" } + ] + }, + "statements": [ + { + "condition": [ + { + "lhs": "amount", + "comparison": "greater_than", + "value": { "type": "number", "value": 10 }, + "metadata": {} + } + ], + "nested": [ + { + "condition": [ + { + "lhs": "card_network", + "comparison": "equal", + "value": { "type": "enum_variant", "value": "Visa" }, + "metadata": {} + } + ], + "nested": null + }, + { + "condition": [ + { + "lhs": "billing_country", + "comparison": "equal", + "value": { "type": "enum_variant", "value": "India" }, + "metadata": {} + } + ], + "nested": null + } + ] + } + ] +} +``` + +## Output Variants + +### Priority Output + +```json +{ + "routing_type": "priority", + "output": { + "priority": [ + { "gateway_name": "adyen", "gateway_id": "mca_adyen" }, + { "gateway_name": "stripe", "gateway_id": "mca_stripe" } + ] + } +} +``` + +### Volume Split Output + +```json +{ + "routing_type": "volume_split", + "output": { + "volume_split": [ + { + "split": 70, + "output": { "gateway_name": "stripe", "gateway_id": "mca_stripe" } + }, + { + "split": 30, + "output": { "gateway_name": "adyen", "gateway_id": "mca_adyen" } + } + ] + } +} +``` + +### Volume Split Priority Output + +Use `volume_split_priority` when each split should return a priority list rather than a single connector. + +```json +{ + "routing_type": "volume_split_priority", + "output": { + "volume_split_priority": [ + { + "split": 60, + "output": [ + { "gateway_name": "stripe", "gateway_id": "mca_stripe" }, + { "gateway_name": "adyen", "gateway_id": "mca_adyen" } + ] + }, + { + "split": 40, + "output": [ + { "gateway_name": "checkout", "gateway_id": "mca_checkout" }, + { "gateway_name": "stripe", "gateway_id": "mca_stripe" } + ] + } + ] + } +} +``` + +## Value Variants + +### Enum Variant Array + +```json +{ + "lhs": "card_network", + "comparison": "equal", + "value": { + "type": "enum_variant_array", + "value": ["Visa", "Mastercard"] + }, + "metadata": {} +} +``` + +### Number Array + +```json +{ + "lhs": "amount", + "comparison": "equal", + "value": { + "type": "number_array", + "value": [1000, 2000, 5000] + }, + "metadata": {} +} +``` + +### Number Comparison Array + +```json +{ + "lhs": "amount", + "comparison": "equal", + "value": { + "type": "number_comparison_array", + "value": [ + { "comparison_type": "greater_than", "number": 1000 }, + { "comparison_type": "less_than_equal", "number": 5000 } + ] + }, + "metadata": {} +} +``` + +## Notes + +- Advanced algorithms require `statements`; top-level `single`, `priority`, and `volume_split` algorithms do not. +- Conditions in the same `condition` array behave like AND. +- Multiple statements behave like OR. +- `nested` allows a parent condition plus nested branch matching. +- `volume_split` percentages should add up to 100. + +## Related + +- [Create Routing Algorithm](./routing-algorithm-create.mdx) +- [Evaluate Routing Algorithm](./routing-algorithm-evaluate.mdx) +- [Priority Routing](./routing-priority-example.mdx) +- [Volume Split Routing](./routing-volume-split-example.mdx) diff --git a/docs/api-refs/routing-algorithm-create.mdx b/docs/api-refs/routing-algorithm-create.mdx index afdef903..1c16f48b 100644 --- a/docs/api-refs/routing-algorithm-create.mdx +++ b/docs/api-refs/routing-algorithm-create.mdx @@ -5,7 +5,18 @@ description: "Curl examples for /routing/create." # Create Routing Algorithm -Use `/routing/create` to persist a rule-based or volume-based routing algorithm. Use the dedicated shape pages for full examples. +Use `/routing/create` to persist a merchant-scoped routing algorithm. Creating an algorithm does not make it active; call [`/routing/activate`](./routing-algorithm-activate.mdx) after creation. + +Supported `algorithm.type` values: + +| Type | Use case | Full example | +| --- | --- | --- | +| `single` | Always return one connector. | [Single connector](./routing-single-connector-example.mdx) | +| `priority` | Return connectors in the configured order. | [Priority routing](./routing-priority-example.mdx) | +| `volume_split` | Split decisions by percentage. | [Volume split](./routing-volume-split-example.mdx) | +| `advanced` | Evaluate AND/OR/nested conditions before returning an output. | [Advanced routing](./routing-advanced-example.mdx) | + +There is no public deactivate route in the current API. To change active behavior, create or select another algorithm and activate it. ## Priority Rule @@ -28,6 +39,102 @@ curl --location "$BASE_URL/routing/create" \ }' ``` +## Single Connector Rule + +```bash +curl --location "$BASE_URL/routing/create" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "single connector rule", + "created_by": "merchant_demo", + "description": "always route to stripe", + "algorithm_for": "payment", + "algorithm": { + "type": "single", + "data": { "gateway_name": "stripe", "gateway_id": "mca_111" } + } + }' +``` + +## Volume Split Rule + +```bash +curl --location "$BASE_URL/routing/create" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "volume split rule", + "created_by": "merchant_demo", + "description": "split traffic between stripe and adyen", + "algorithm_for": "payment", + "algorithm": { + "type": "volume_split", + "data": [ + { + "split": 70, + "output": { "gateway_name": "stripe", "gateway_id": "mca_111" } + }, + { + "split": 30, + "output": { "gateway_name": "adyen", "gateway_id": "mca_112" } + } + ] + } + }' +``` + +## Advanced Rule + +Use `advanced` for conditional routing. The complete AND/OR/nested reference is in [Advanced Routing Example](./routing-advanced-example.mdx). + +```bash +curl --location "$BASE_URL/routing/create" \ + --header "$AUTH_HEADER" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "advanced card rule", + "created_by": "merchant_demo", + "description": "route Visa cards to adyen first", + "algorithm_for": "payment", + "algorithm": { + "type": "advanced", + "data": { + "globals": {}, + "default_selection": { + "priority": [{ "gateway_name": "stripe", "gateway_id": "mca_111" }] + }, + "rules": [ + { + "name": "visa_card_rule", + "routing_type": "priority", + "output": { + "priority": [ + { "gateway_name": "adyen", "gateway_id": "mca_112" }, + { "gateway_name": "stripe", "gateway_id": "mca_111" } + ] + }, + "statements": [ + { + "condition": [ + { + "lhs": "card_network", + "comparison": "equal", + "value": { "type": "enum_variant", "value": "Visa" }, + "metadata": {} + } + ], + "nested": null + } + ] + } + ], + "metadata": {} + } + } + }' +``` + ## Response ```json @@ -38,3 +145,10 @@ curl --location "$BASE_URL/routing/create" \ "modified_at": "2026-04-25 11:45:03" } ``` + +## Related + +- [Activate Routing Algorithm](./routing-algorithm-activate.mdx) +- [List Routing Algorithms](./routing-algorithm-list.mdx) +- [Evaluate Routing Algorithm](./routing-algorithm-evaluate.mdx) +- [Advanced Routing Example](./routing-advanced-example.mdx) diff --git a/docs/api-refs/routing-volume-split-example.mdx b/docs/api-refs/routing-volume-split-example.mdx index ed45155b..c3c2750c 100644 --- a/docs/api-refs/routing-volume-split-example.mdx +++ b/docs/api-refs/routing-volume-split-example.mdx @@ -18,11 +18,11 @@ curl --location "$BASE_URL/routing/create" \ "data": [ { "split": 70, - "connectors": [{ "gateway_name": "stripe", "gateway_id": "mca_111" }] + "output": { "gateway_name": "stripe", "gateway_id": "mca_111" } }, { "split": 30, - "connectors": [{ "gateway_name": "adyen", "gateway_id": "mca_112" }] + "output": { "gateway_name": "adyen", "gateway_id": "mca_112" } } ] } diff --git a/docs/api-refs/update-score-legacy.mdx b/docs/api-refs/update-score-legacy.mdx index 54f0c38e..63b1dab1 100644 --- a/docs/api-refs/update-score-legacy.mdx +++ b/docs/api-refs/update-score-legacy.mdx @@ -5,7 +5,7 @@ description: "Compatibility example for the legacy /update-score route." # Legacy Update Score -`/update-score` is retained for compatibility. New integrations should use [`/update-gateway-score`](/api-refs/update-gateway-score). +`/update-score` is retained for compatibility. New integrations should use [`/update-gateway-score`](./update-gateway-score.mdx). ```bash curl --location "$BASE_URL/update-score" \ diff --git a/docs/configuration.md b/docs/configuration.md index 78044cb3..40d630cf 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -61,7 +61,7 @@ Use environment variables to override selected runtime values when needed (for e For deployment-specific examples, see: - [Local Setup Guide](local-setup.md) -- [Helm Chart README](../helm-charts/README.md) +- [Helm Chart README](https://github.com/juspay/decision-engine/blob/main/helm-charts/README.md) ## Related Docs diff --git a/docs/mint.json b/docs/mint.json index 3aeaa1fe..44cce735 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -11,7 +11,6 @@ "light": "#4D9CFF", "dark": "#0050B4" }, - "openapi": ["openapi.json"], "api": { "baseUrl": "http://localhost:8080", "playground": { @@ -27,12 +26,13 @@ "local-setup", "configuration", "dashboard-guide", + "api-overview", "api-reference", "dual-protocol-layer" ] }, { - "group": "API Examples", + "group": "API Examples (curl flows)", "pages": [ "api-refs/api-ref", "api-refs/health-check", @@ -87,7 +87,7 @@ ] }, { - "group": "Health", + "group": "OpenAPI: Health", "pages": [ "api-reference/endpoint/healthCheck", "api-reference/endpoint/healthReady", @@ -95,15 +95,15 @@ ] }, { - "group": "Gateway Decision", + "group": "OpenAPI: Gateway Decision", "pages": ["api-reference/endpoint/decideGateway"] }, { - "group": "Score Feedback", + "group": "OpenAPI: Score Feedback", "pages": ["api-reference/endpoint/updateGatewayScore"] }, { - "group": "Merchant Account", + "group": "OpenAPI: Merchant Account", "pages": [ "api-reference/endpoint/createMerchant", "api-reference/endpoint/getMerchant", @@ -113,7 +113,7 @@ ] }, { - "group": "Routing Rules", + "group": "OpenAPI: Routing Rules", "pages": [ "api-reference/endpoint/createRoutingRule", "api-reference/endpoint/activateRoutingRule", @@ -124,7 +124,7 @@ ] }, { - "group": "Rule Configuration", + "group": "OpenAPI: Rule Configuration", "pages": [ "api-reference/endpoint/createRuleConfig", "api-reference/endpoint/getRuleConfig", @@ -133,7 +133,7 @@ ] }, { - "group": "Auth And API Keys", + "group": "OpenAPI: Auth And API Keys", "pages": [ "api-reference/endpoint/signup", "api-reference/endpoint/login", @@ -148,7 +148,7 @@ ] }, { - "group": "Analytics", + "group": "OpenAPI: Analytics", "pages": [ "api-reference/endpoint/analyticsOverview", "api-reference/endpoint/analyticsGatewayScores", @@ -160,7 +160,7 @@ ] }, { - "group": "Compatibility And Config", + "group": "OpenAPI: Compatibility And Config", "pages": [ "api-reference/endpoint/legacyDecisionGateway", "api-reference/endpoint/legacyUpdateScore",