API reference

Complete reference for the PayInference HTTP API. All requests and responses are JSON. All amounts are integers in minor units. All identifiers and enum values are snake_case.

Base URL. Production is https://api.payinference.com. Local development uses http://localhost:4000; the curl examples below use the local base URL so they run against pnpm dev as-is.

Authentication. Send an API key in the x-api-key header. Each endpoint lists its required scope. See Authentication.

Common response headers. Every response carries x-request-id, useful when reporting issues.

Errors. 400 validation errors return { "error": "validation_error", "issues": [...] }. See Errors.

Endpoints:

Endpoints not covered here: /v1/auth/*, /v1/api-keys, /v1/team, /v1/analytics/summary, /v1/alerts, /v1/integrations (including PUT /v1/integrations/:provider/webhook-secret, which sets or rotates a per-merchant webhook signing secret, write-only), and /v1/admin/* require a dashboard session (not an API key) and back the dashboard UI. POST /v1/provider-webhooks/:providerSlug/:merchantId is the signed provider webhook intake described in Payment Intelligence.

POST /v1/decision#

Creates one decision for one payment attempt. Designed for a sub-50 ms server-side budget; call it from your backend immediately before executing the payment.

• Auth: x-api-key with scope decision:write
• Headers: content-type: application/json, optional Idempotency-Key
• Idempotency: optional Idempotency-Key header (max 255 chars). Retries with the same key replay the stored response (marked idempotency-replayed: true) for one hour. Without a key, every call creates a new decision_id. Keep order_id stable across attempts of the same order. See Idempotency and retries.
• Latency guidance: set a hard client timeout (50 to 250 ms) and a fallback path. The response's decision_latency_ms reports server-side time.

Request body#

The body is strict: unknown fields anywhere are rejected with 400 validation_error. This is the mechanism that keeps card data out of PayInference.

transaction:

previous_attempt:

risk_signals (all optional, all non-sensitive aggregates):

Example request#

curl -s http://localhost:4000/v1/decision \
  -H "content-type: application/json" \
  -H "x-api-key: $PAYINFERENCE_API_KEY" \
  -d '{
    "merchant_id": "m_123",
    "order_id": "order_456",
    "transaction": {
      "amount": 14900,
      "currency": "USD",
      "country": "US",
      "payment_method": "card",
      "card_network": "visa",
      "transaction_type": "authorization",
      "customer_type": "returning",
      "risk_score": 42
    },
    "available_providers": ["stripe", "adyen", "paypal"],
    "risk_signals": {
      "velocity_count_1h": 3,
      "previous_success_count": 12,
      "device_risk_band": "low",
      "ip_country_match": true
    }
  }'

Response body#

risk:

provider_health (map keyed by provider, only providers you listed):

policy:

model:

Cost-aware routing (deterministic-v2) activates for a merchant when its policy declares cost controls or resolved pricing is cached (contract upload via POST /v1/pricing/rules, or webhook-derived observed fees). The cost and economics blocks are populated on those decisions; on deterministic-v1 decisions both fields are null.

cost (when present):

economics (when present):

Example response#

{
  "decision_id": "dec_9f3a1c0b22d14e55",
  "merchant_id": "m_123",
  "mode": "live",
  "decision_mode": "enforce",
  "action": "route",
  "route": { "primary_provider": "adyen", "fallback_provider": "stripe" },
  "risk": {
    "score": 0,
    "band": "low",
    "recommended_action": "route",
    "reason_codes": [
      "NORMAL_AMOUNT_FOR_MERCHANT",
      "RETURNING_CUSTOMER",
      "PRIOR_SUCCESSFUL_PAYMENTS",
      "MERCHANT_SUPPLIED_ELEVATED_RISK"
    ]
  },
  "provider_health": {
    "adyen": { "score": 94, "state": "healthy", "confidence": 91, "source": "probe" },
    "stripe": { "score": 68, "state": "degraded", "confidence": 88, "source": "probe" },
    "paypal": { "score": 82, "state": "watch", "confidence": 74, "source": "probe" }
  },
  "policy": {
    "policy_id": "policy_m_123_v1",
    "policy_version": "1.0.0",
    "matched_rules": ["avoid_degraded_providers"]
  },
  "model": {
    "model_version": "deterministic-v1",
    "route_scores": { "adyen": 0.91, "paypal": 0.77, "stripe": 0.64 }
  },
  "cost": null,
  "economics": null,
  "reason_codes": ["ADYEN_HEALTHY_FOR_SEGMENT", "HIGHER_EXPECTED_APPROVAL_RATE", "RISK_ACCEPTABLE"],
  "decision_latency_ms": 11.4,
  "ttl_ms": 3000
}

Example responses for every instruction (use_default_route, step_up, hold, retry, failover, block) are on Decision instructions.

Errors#

Production notes#

• Log decision_id next to your PSP charge id on every attempt.
• Treat a timeout as an outage, not a block. Fall back per your own policy. See Production integration.
• Respect ttl_ms: decide, then execute immediately.

POST /v1/outcomes#

Reports the result of executing a decision. Idempotent per decision_id (upsert).

• Auth: x-api-key with scope outcome:write
• Idempotency: reporting again with the same decision_id updates the stored outcome.

Request body#

Outcome values: approved, soft_declined, hard_declined, technical_failed, timeout, rate_limited, blocked, step_up_completed, step_up_failed. Legacy aliases declined, error, cancelled are accepted and normalized. See Outcome feedback for when to use each.

Example#

curl -s http://localhost:4000/v1/outcomes \
  -H "content-type: application/json" \
  -H "x-api-key: $PAYINFERENCE_API_KEY" \
  -d '{
    "decision_id": "dec_9f3a1c0b22d14e55",
    "order_id": "order_456",
    "provider_used": "adyen",
    "outcome": "soft_declined",
    "provider_latency_ms": 604,
    "provider_reason_code": "insufficient_funds",
    "amount": 14900,
    "currency": "USD"
  }'

{
  "outcome_id": "out_7c1d92",
  "decision_id": "dec_9f3a1c0b22d14e55",
  "outcome": "soft_declined",
  "failure_class": "soft_decline",
  "technical_failure_type": null,
  "approved": false
}

Errors#

GET /v1/provider-health#

Returns the current cached health snapshot per provider segment. This endpoint reads stored snapshots only; it never probes a provider.

• Auth: x-api-key with scope health:read

curl -s http://localhost:4000/v1/provider-health -H "x-api-key: $PAYINFERENCE_API_KEY"

{
  "providers": [
    {
      "provider": "adyen",
      "segment_key": "adyen:card:USD",
      "score": 94,
      "state": "healthy",
      "confidence": 91,
      "p95_latency_ms": 412,
      "timeout_rate": 0.002,
      "error_5xx_rate": 0.001,
      "throttle_429_rate": 0,
      "approval_rate": 0.93,
      "approval_rate_baseline": 0.91,
      "webhook_lag_seconds": 4,
      "sample_size": 1240,
      "window_seconds": 300,
      "reason_codes": ["HEALTHY_FOR_SEGMENT"],
      "updated_at": "2026-07-01T12:00:00.000Z"
    }
  ]
}

Field meanings are covered in Payment Intelligence.

GET /v1/decisions#

Lists decisions for your workspace, newest first. Merchant-scoped keys see only their merchant's decisions.

• Auth: x-api-key with scope policy:read
• Query parameters: page_size (default 25, max 100), action (filter to one instruction, e.g. hold), decision_mode (shadow or enforce), unresolved=true (only decisions with neither an outcome nor a review — with action=hold this is the held-payment review queue; see Hold and review integration), range (24h, 7d, 30d, 90d, or all — the default; an unknown value falls back to all), and order_id (exact match on your own order id — returns every decision recorded for that order, including retries). Shadow decisions are advisory and never appear in the unresolved queue.
• Pagination: cursor-based, keyed by decision_id. Pass starting_after=<decision_id> for rows older than that decision, or ending_before=<decision_id> for rows newer; has_more says whether more rows exist in the direction you are walking. Cursor responses omit total (no count scan per page). Offset paging (page, default 1) is still accepted for shallow reads and includes total, but is capped at the first 10 000 rows — walk cursors for deeper history. At enterprise volumes cursor cost stays flat at any depth; offset cost does not.

curl -s "http://localhost:4000/v1/decisions?page_size=25" -H "x-api-key: $PAYINFERENCE_API_KEY"
# next (older) page:
curl -s "http://localhost:4000/v1/decisions?page_size=25&starting_after=dec_9f3a1c0b22d14e55" -H "x-api-key: $PAYINFERENCE_API_KEY"

{
  "page": 1,
  "page_size": 25,
  "total": 1204,
  "has_more": true,
  "decisions": [
    {
      "decision_id": "dec_9f3a1c0b22d14e55",
      "merchant_id": "m_123",
      "order_id": "order_456",
      "created_at": "2026-07-01T12:00:00.000Z",
      "mode": "live",
      "decision_mode": "enforce",
      "action": "route",
      "primary_provider": "adyen",
      "fallback_provider": "stripe",
      "amount": 14900,
      "amount_bucket": "100_500",
      "currency": "USD",
      "country": "US",
      "payment_method": "card",
      "risk_score": 22,
      "risk_band": "low",
      "provider_health_source": "probe",
      "decision_latency_ms": 11.4,
      "reason_codes": ["ADYEN_HEALTHY_FOR_SEGMENT"],
      "model_version": "deterministic-v1",
      "matched_rules": [],
      "review": null,
      "outcome": {
        "outcome": "approved",
        "provider_used": "adyen",
        "provider_latency_ms": 842,
        "failure_class": "none"
      }
    }
  ]
}

GET /v1/decisions/aggregate#

Lifetime decision aggregates for your workspace — instruction mix, provider share, risk bands, outcome counts, approval/feedback rates, and latency percentiles — computed by the database over your full recorded history and cached briefly server-side. Use this for headline stats instead of paging the list and folding rows yourself.

• Auth: x-api-key with scope policy:read

curl -s "http://localhost:4000/v1/decisions/aggregate" -H "x-api-key: $PAYINFERENCE_API_KEY"

{
  "total": 1204,
  "by_action": [{ "action": "route", "count": 800 }],
  "by_provider": [{ "provider": "adyen", "count": 640 }],
  "by_risk_band": [{ "band": "low", "count": 900 }],
  "top_reason_codes": [{ "code": "ADYEN_HEALTHY_FOR_SEGMENT", "count": 512 }],
  "reason_code_sample": 500,
  "outcome_counts": [{ "outcome": "approved", "count": 700 }],
  "with_outcome": 950,
  "approved": 720,
  "approval_rate": 0.7579,
  "feedback_rate": 0.789,
  "avg_latency_ms": 9.2,
  "p95_latency_ms": 41.5,
  "recent": [],
  "generated_at": "2026-07-21T12:00:00.000Z",
  "source": "live"
}

top_reason_codes is computed over the reason_code_sample most recent decisions (reason codes live in a JSON array, so exact lifetime counts would require a full-table scan); every other figure is exact over your full history. recent carries the 8 newest decisions in the list-row shape. source is cache when served from the short-lived server cache, live when computed for this request.

GET /v1/decisions/shadow-report#

Evaluates shadow traffic: how the would-have-been instructions compare with what your own logic actually did. Comparable wherever an outcome was reported — provider_used is what you executed, the decision row is what PayInference would have instructed. Use it to judge decision quality on real traffic before switching to enforce.

• Auth: x-api-key with scope policy:read
• Query parameters: days (window, default 30, max 90)

{
  "window_days": 30,
  "since": "2026-06-19T00:00:00.000Z",
  "total_shadow_decisions": 1820,
  "decisions_with_outcome": 1714,
  "truncated": false,
  "actions": { "route": 1650, "step_up": 120, "hold": 38, "block": 12 },
  "route_comparison": {
    "comparable": 1602,
    "merchant_used_recommended": 1231,
    "merchant_used_fallback": 88,
    "merchant_diverged": 283,
    "agreement_rate": 0.8234,
    "approval_rate_when_followed": 0.914,
    "approval_rate_when_diverged": 0.861
  }
}

agreement_rate is the share of comparable decisions where your stack used the recommended (or pre-approved fallback) provider. The two approval rates answer the question shadow mode exists for: did payments do better when your logic agreed with the instruction than when it diverged?

POST /v1/decisions/:decisionId/review#

Resolves a held decision from the built-in review queue: { "resolution": "approve" } or { "resolution": "reject", "note": "…" } (note optional, ≤ 500 chars). Approve marks the review resolved — your backend still executes and reports the outcome. Reject records outcome blocked with reason code HOLD_REVIEW_REJECTED. One review per decision; conflicts (already reviewed, outcome already reported, not a hold, or a shadow decision — shadow holds are advisory and cannot be reviewed) return 409.

• Auth: dashboard session only, roles owner/admin/analyst — API keys cannot resolve reviews. Merchant backends poll GET /v1/decisions instead.

GET /v1/decisions/:decisionId#

Full detail for one decision: the route, risk assessment, matched policy rules, per-provider evaluations with exclusion reasons, model scores, the review resolution for held decisions, and the joined outcome. This is the endpoint to use when debugging why a decision went the way it did.

• Auth: x-api-key with scope policy:read

curl -s http://localhost:4000/v1/decisions/dec_9f3a1c0b22d14e55 -H "x-api-key: $PAYINFERENCE_API_KEY"

Response (abridged; see Observability for how to read it):

{
  "decision_id": "dec_9f3a1c0b22d14e55",
  "merchant_id": "m_123",
  "order_id": "order_456",
  "created_at": "2026-07-01T12:00:00.000Z",
  "mode": "live",
  "action": "route",
  "route": { "primary_provider": "adyen", "fallback_provider": "stripe" },
  "provider_health_source": "probe",
  "risk": { "score": 22, "band": "low", "recommended_action": "route", "reason_codes": [] },
  "transaction": { "amount": 14900, "currency": "USD", "country": "US", "payment_method": "card" },
  "policy": {
    "policy_id": "policy_m_123_v1",
    "policy_version": "1.0.0",
    "matched_rules": ["avoid_degraded_providers"]
  },
  "model": { "model_version": "deterministic-v1", "provider_scores": {} },
  "reason_codes": ["ADYEN_HEALTHY_FOR_SEGMENT"],
  "decision_latency_ms": 11.4,
  "ttl_ms": 3000,
  "provider_evaluations": [
    {
      "provider": "stripe",
      "eligible": false,
      "route_score": 0,
      "health_score": 68,
      "health_state": "degraded",
      "exclusion_reason": "POLICY_EXCLUDED_PROVIDER",
      "components": null
    }
  ],
  "outcome": {
    "outcome": "approved",
    "provider_used": "adyen",
    "provider_latency_ms": 842,
    "provider_reason_code": "approved",
    "failure_class": "none",
    "technical_failure_type": null,
    "approved": true,
    "reported_at": "2026-07-01T12:00:03.000Z"
  }
}

Errors: 404 for an unknown decision or one outside your workspace or merchant scope.

POST /v1/policies#

Creates a policy, optionally publishing it immediately. Publishing archives any previously published policy: one live policy per merchant.

• Auth: x-api-key with scope policy:write

Request body#

Example#

curl -s http://localhost:4000/v1/policies \
  -H "content-type: application/json" \
  -H "x-api-key: $PAYINFERENCE_API_KEY" \
  -d '{
    "merchant_id": "m_123",
    "name": "High value protection",
    "default_provider": "stripe",
    "publish": true,
    "rules": [
      {
        "rule_id": "high_value_step_up",
        "name": "Step up high value new customers",
        "priority": 10,
        "enabled": true,
        "when": { "amount_gte": 50000, "customer_type_in": ["new", "guest"] },
        "then": { "type": "step_up" }
      }
    ]
  }'

Response: { "policy": { …full validated policy… }, "db_id": "…", "warnings": [] }.

Validation errors return 400 with { "error": "policy_validation_failed", "issues": [...] }. Errors always reject; warnings reject only on publish (drafts may be saved incomplete).

POST /v1/policies/translate#

Drafts a structured policy from plain English. The translator is rule-based, runs nowhere near the decision path, and its output must round-trip strict schema validation before it can be shown or saved. Nothing is persisted by this endpoint.

• Auth: x-api-key with scope policy:write

curl -s http://localhost:4000/v1/policies/translate \
  -H "content-type: application/json" \
  -H "x-api-key: $PAYINFERENCE_API_KEY" \
  -d '{ "merchant_id": "m_123", "text": "Prefer Adyen for EU cards. Require 3DS above 500 EUR. Never retry hard declines." }'

Response: { "draft": { …policy… } | null, "warnings": [...], "valid": true | false }.

POST /v1/policies/simulate#

Evaluates a policy (a draft you pass inline, or the merchant's published policy when omitted) against a sample transaction using the same engine and cached provider health as the live Decision API. Nothing is persisted, and no live decision is affected.

• Auth: x-api-key with scope policy:read

Request body#

Response includes action, route, risk, matched_rules, excluded_providers, provider_evaluations, route_scores, reason_codes, and validation for the simulated policy.

GET /v1/policies/:merchantId#

Lists all policies for a merchant with their status (draft, published, archived), version, and rules.

• Auth: x-api-key with scope policy:read

curl -s http://localhost:4000/v1/policies/m_123 -H "x-api-key: $PAYINFERENCE_API_KEY"

{
  "policies": [
    {
      "policy_id": "policy_m_123_01h9…",
      "name": "High value protection",
      "status": "published",
      "version": "1.0.0",
      "default_provider": "stripe",
      "rules": [ … ],
      "updated_at": "2026-07-01T12:00:00.000Z"
    }
  ]
}

GET /health and GET /ready#

Public liveness and readiness probes, intended for load balancers and orchestration.

curl -s http://localhost:4000/health
# { "status": "ok", "service": "payinference-api", "time": "…" }

curl -s http://localhost:4000/ready
# { "status": "ready", "checks": { "postgres": "ok", "redis": "ok" } }

/ready returns 503 with per-dependency status when Postgres or Redis is unreachable.