Core concepts

These are the terms the rest of the documentation uses. They map one-to-one to things in the API.

Payment decision infrastructure#

PayInference sits between "customer clicked pay" and "payment submitted to a provider". Your backend asks it what should happen to a payment, and it returns one instruction. It is not a PSP, gateway, orchestrator, wallet, or fraud tool. It never moves money and it is never in the card-data path.

Payment context#

The safe, non-sensitive facts about a payment attempt that 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 strict request schema.

Payment Intelligence#

The data side of the platform. Intelligence Agents are background workers that continuously collect and normalize provider health, latency, failure spikes, webhook lag, outcome history, and pricing. They run outside the checkout path and write cached snapshots that the Decision API reads at request time. See Payment Intelligence.

Policy Manager#

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

Inference Engine#

The component that combines cached intelligence, the published policy, deterministic risk scoring, and route scoring into a single decision. Two engine generations are live: deterministic-v1 (health- and policy-driven routing) and the cost-aware deterministic-v2, which activates per merchant when policy cost controls or resolved pricing exist and ranks routes by expected value in money terms. Every response carries the model.model_version that produced it. No LLM and no external call runs on the decision path.

Decision API#

The synchronous API your backend calls: POST /v1/decision. It reads only cached inputs plus pure computation and is designed for a sub-50 ms decision budget. See Decision API.

Instruction#

The single actionable output of a decision, carried 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. In enforce (the default) your stack executes the instruction. In shadow the decision is computed and recorded identically, but it is advisory: your existing payment logic keeps executing, and the joined outcome shows what the instruction would have changed. 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, machine-readable, UPPER_SNAKE strings that explain a decision, for example ADYEN_HEALTHY_FOR_SEGMENT or RETRY_SUPPRESSED_BY_POLICY. They are the only explanation surface on the hot path: never free text, never PII. Use them for logging, analytics, and support.

Decision log#

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

Outcome feedback#

After you execute an instruction, you report what actually happened 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, analytics, and policy evaluation. See Outcome feedback.

Observability#

The record of what happened and why: decision logs, reason codes, policy results, outcomes, audit trail, latency metrics, and OpenTelemetry traces. See Observability.

Agentic payments#

Payments initiated or requested by software agents rather than a human at a checkout page. The same decision primitives apply: policies can cap amounts, require step-up, or block, and the agent's backend executes the instruction. PayInference does not custody funds or execute payments for agents. See Agentic payments.

Terminology quick reference#