Skip to main content
A decision is the result of evaluating a transaction against an active ruleset. Request one with POST /api/decisions: Specter returns an outcome and logs the decision for later retrieval and reporting.

​
Outcomes

Every decision resolves to one of four outcomes.
OutcomeMeaning
ALLOWNo blocking rule matched — the default when nothing fires.
REVIEWA rule flagged the transaction for manual review. REVIEW outcomes accumulate across rules.
BLOCKA blocking rule matched. Evaluation short-circuits on the first BLOCK.
PROVISIONALAn interim outcome while an asynchronous evaluation is still pending.
Specter is designed to fail open: if a backend errors or times out and the rule’s on_error is allow, Specter skips that backend rather than blocking the customer. See the rule engine.

​
The decision request

Three attributes are always required; everything else is optional but enriches the evaluation.
​
credential
object
required
Card credential — type: "pan", "masked_pan", or "sepa". A pan credential is only accepted on an SAQ_D or ROC instance; on the default SAQ_A level it is rejected — see Instance configuration.
​
customer
object
required
Must contain id.
​
transaction
object
required
Must contain reference, amount (minor units), and currency (ISO 4217).
​
device
object
IP address, fingerprint, user agent, session, and language.
​
billing
object
Addresses forwarded to applicable backends.
​
shipping
object
Addresses forwarded to applicable backends.
​
items
array
Cart line items; each needs at least name or sku.
​
airline
object
Travel data (passengers, legs) forwarded to backends that consume it.
​
metadata
object
Flat string key-value pairs, available to rules as $.metadata.*. Never forwarded to backends.
​
context
string
default:"default"
Selects which ruleset to evaluate.
See API integration for the full schema.

​
The decision response

{
  "id": "dec_01J...",
  "decision": "REVIEW",
  "context": "checkout",
  "credential_fingerprint": "crd_4ba218...",
  "credential_type": "pan",
  "triggered_rules": [
    { "id": "ravelin-assessment", "type": "backend", "action": "REVIEW" }
  ],
  "backend_results": [
    {
      "backend": "link-prod/ravelin",
      "decision": "REVIEW",
      "raw_response": { "...": "..." }
    }
  ]
}
​
decision
string
The outcome.
​
triggered_rules
array
Rules that fired, in evaluation order.
​
backend_results
array
One entry per executed backend rule, including any error such as insufficient_context. Present only on Specter Connect.
​
credential_fingerprint
string
HMAC-SHA256 identifier for the card instrument.

​
The decision log

Every decision is written to the log. When a PAN is sent, only its fingerprint is returned. Retrieve a past decision with GET /api/decisions/{id}.

​
Resolving a REVIEW decision

A REVIEW decision is not final — it asks for a human judgement. Once your team has reviewed the transaction, resolve it to record the accept/reject outcome and forward it to the backends that flagged it: 
POST /api/decisions/{id}/resolve
Requires the decisions:write scope.
  • Only decisions with decision: "REVIEW" can be resolved — others return 422.
  • Each decision can be resolved once — a second attempt returns 409.

​
Request

​
action
string
required
accept or reject.
​
reason
string
Free-text note stored on the resolution.
{
  "action": "accept",
  "reason": "manual review passed"
}

​
Response

{
  "decision_id": "dec_01J...",
  "original_decision": "REVIEW",
  "resolution": "ACCEPTED",
  "resolved_at": "2026-03-17T12:00:00Z",
  "backend_notifications": [
    { "backend": "link-prod/vdm", "status": "ok" },
    { "backend": "link-prod/ravelin", "status": "skipped" }
  ]
}
The resolution is stored on the decision and returned by subsequent GET /api/decisions/{id} calls. Only backends that produced a REVIEW result participate; Specter forwards the outcome to each through its Link integration, and a backend that does not support resolution is skipped.
StatusMeaning
okThe backend accepted the resolution.
skippedThe backend does not support resolution.
reference_unavailableThe backend’s stored response lacked a required reference.

Rule engine

How rules combine to produce an outcome.

Lifecycle events

Feed transaction outcomes back to Specter and its backends.