Core concepts

The terms the rest of the documentation uses. Each maps one-to-one to something in the API.

Payment decision infrastructure#

PayInference sits between "customer clicked pay" and "payment submitted to a provider". Your backend asks what should happen; it returns one instruction. It never moves money and is never in the card-data path.

Payment context#

The safe facts you send in a decision request: amount in minor units, currency, country, payment method, card network, customer type, optional risk signals, and the providers you can execute on.

Card numbers, CVVs, emails, and addresses are rejected by the request schema.

Payment Intelligence#

Background workers that collect and normalize provider health, latency, failure spikes, webhook lag, outcome history, and pricing. They run outside the checkout path and write cached snapshots the Decision API reads at request time. See Payment Intelligence.

Policy Manager#

Where merchants define the rules a decision must respect — routing, risk thresholds, retry limits, step-up, blocks, fallbacks, and cost controls. Policies are structured JSON, validated before publish, versioned, and evaluated deterministically. See Policy Manager.

Inference Engine#

Combines cached intelligence, the published policy, risk scoring, and route scoring into one decision. No LLM and no external call runs on the decision path.

Two generations are live: deterministic-v1 routes on health and policy; deterministic-v2 adds cost-awareness, ranking routes by expected value in money terms, and activates per merchant once cost controls or resolved pricing exist. Every response carries the model.model_version that produced it.

Decision API#

The synchronous endpoint your backend calls: POST /v1/decision. Cached inputs and pure computation only, on a sub-50 ms budget. See Decision API.

Instruction#

The single actionable output, in the action field: route, use_default_route, step_up, hold, retry, failover, or block. Your backend executes it; PayInference never executes anything. See Decision instructions.

Shadow and enforce modes#

How your backend treats the instruction, set per request with decision_mode.

GET /v1/decisions/shadow-report aggregates the comparison, so you can judge decision quality on real traffic before enforcing. See Shadow and enforce modes.

Reason codes#

Stable UPPER_SNAKE strings explaining a decision — ADYEN_HEALTHY_FOR_SEGMENT, RETRY_SUPPRESSED_BY_POLICY. The only explanation surface on the hot path: never free text, never PII.

Decision log#

Every decision, persisted off the critical path with its input summary, matched rules, provider evaluations, reason codes, and latency. Query GET /v1/decisions and GET /v1/decisions/:decisionId, or browse it in the dashboard.

Outcome feedback#

What actually happened, reported to POST /v1/outcomes: approved, soft_declined, hard_declined, technical_failed, timeout, rate_limited, blocked, step_up_completed, or step_up_failed. Outcomes power provider health, retry intelligence, and analytics. See Outcome feedback.

Observability#

Decision logs, reason codes, policy results, outcomes, audit trail, latency metrics, and OpenTelemetry traces. See Observability.

Agentic payments#

Payments initiated by software agents rather than a human at checkout. The same primitives apply: policies can cap amounts, require step-up, or block. PayInference does not custody funds or execute payments for agents. See Agentic payments.

Terminology quick reference#