PayinferenceDocs
payinference.com

Payment Intelligence

Payment Intelligence is the data side of PayInference. It prepares everything a decision needs before the decision is requested, so the Decision API can answer from cache in milliseconds.

Intelligence comes from three sources:

  1. PayInference-owned Intelligence Agents. Background workers that probe providers, ingest provider webhooks, aggregate outcomes, and sync pricing.
  2. Merchant-provided data. The payment context and optional risk_signals you send on each decision request, plus contract pricing you configure.
  3. Outcome feedback. What you report to POST /v1/outcomes after executing each instruction.

Intelligence Agents run outside the checkout path#

This is the core design rule. Probing a provider takes hundreds of milliseconds and can fail; calling providers inline would make a sub-50 ms budget impossible and would import every provider outage into your checkout. Instead:

  • Agents run continuously in a background worker fleet (synthetic provider probes on a seconds cadence, webhook ingestion, outcome and analytics aggregation, pricing sync).
  • Each agent normalizes what it collects and writes snapshots to a cache and to history storage.
  • At request time the Decision API only reads cached snapshots: provider health, the published policy, and resolved pricing. It performs no provider call, no blocking write, and no model-service call.

Decisions are therefore made on data that is seconds old, by design. Every decision response carries ttl_ms so you know the freshness window, and every health snapshot carries updated_at, sample_size, and window_seconds so you can judge the data behind it.

What the agents collect and normalize#

Signal Source Feeds
Provider availability, latency, error and timeout rates Synthetic probes Health score and state per provider segment
Failure spikes and throttling Probes plus your reported outcomes Health state transitions, circuit logic
Approval rates vs baseline Outcome feedback Health score, route scoring
Webhook lag Provider webhook ingestion Health confidence
Retry history previous_attempt context and outcomes Retry and failover decisions
Risk inputs Your risk_signals and transaction context Deterministic risk scoring
Cost inputs Contract pricing, fee uploads, observed fees, settlement and invoice reports Cost-aware routing (deterministic-v2, future implementation)
Payment and customer context Decision requests Segmentation of all of the above

Health snapshot fields#

GET /v1/provider-health (scope health:read) returns the current snapshot per provider segment:

Field Meaning
provider, segment_key Which provider and traffic segment the snapshot describes
score 0 to 100 composite health score
state healthy, watch, degraded, critical, unavailable, unknown
confidence 0 to 100; how much data backs the score
p95_latency_ms, timeout_rate, error_5xx_rate, throttle_429_rate Technical quality of the provider
approval_rate, approval_rate_baseline Current vs expected approval performance
webhook_lag_seconds How far behind the provider's webhooks are
sample_size, window_seconds How much data, over what window
reason_codes Machine-readable state explanation
updated_at Snapshot time

Honesty rules#

Payment Intelligence never fakes certainty:

  • Every snapshot carries a source provenance tag: probe (synthetic probe data), live (real event data), partial (low sample or stale), demo (local demo data), unknown (not enough data).
  • Low-sample or stale segments surface as partial or unknown, never as healthy.
  • Cost estimates carry a pricing_source; estimated_fallback and unknown pricing is flagged and can be barred from driving cost optimization by policy.
  • Decisions record which health source backed the chosen route (provider_health_source in the decision log).

Pricing intelligence#

Cost-aware routing (deterministic-v2) resolves pricing off the hot path from sources in descending trust order: merchant contract overrides (POST /v1/pricing/rules), manual fee uploads, provider observed fees (learned from webhook-declared fees by a background job), settlement reports, invoice reports, balance transactions, then a clearly marked estimated_fallback. The resolved result is cached per merchant and per currency, and the Decision API only reads that cache. Cost never triggers a provider call at decision time, and observed-fee learning requires a minimum evidence window before any rule is derived — a handful of fees never becomes pricing.

What this means for your integration#

  • Send outcome feedback for every executed decision. It is the highest-leverage input you control; without it, health leans on synthetic probes alone and confidence drops.
  • Send risk_signals when you have them. They are optional, but they sharpen risk scoring with data only you have.
  • Do not poll GET /v1/provider-health in a tight loop. Snapshots update on background cadence.
Payinference documentation