Decisions

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.

Outcome	Meaning
`ALLOW`	No blocking rule matched — the default when nothing fires.
`REVIEW`	A rule flagged the transaction for manual review. `REVIEW` outcomes accumulate across rules.
`BLOCK`	A blocking rule matched. Evaluation short-circuits on the first `BLOCK`.
`PROVISIONAL`	An 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.

object

required

Payment credential — type: "pan", "masked_pan", "sepa", or "paypal". 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.

object

required

Must contain id.

object

required

Must contain reference, amount (minor units), and currency (ISO 4217).

object

IP address, fingerprint, user agent, session, and language.

object

Addresses forwarded to applicable backends.

object

Addresses forwarded to applicable backends.

array

Cart line items; each needs at least name or sku.

object

Travel data (passengers, legs) forwarded to backends that consume it.

object

Flat string key-value pairs, available to rules as $.metadata.*. Forwarded to backends and stored on the decision record, so treat it as data you share with your backend providers.

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": { "...": "..." }
    }
  ]
}

string

The outcome.

array

Rules that fired, in evaluation order.

array

One entry per executed backend rule, including any error such as insufficient_context. Present when the ruleset includes backend rules.

string

HMAC-SHA256 identifier for the payment credential.

The decision log

Every decision is written to the log. Raw credential identifiers (PAN, IBAN, PayPal email) are never stored: the log keeps only the credential fingerprint and a masked form. 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

string

required

accept or reject.

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.

Status	Meaning
`ok`	The backend accepted the resolution.
`skipped`	The backend does not support resolution.
`reference_unavailable`	The 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.

Getting Started

Concepts

Integration Patterns

Outcomes

The decision request

The decision response

The decision log

Resolving a REVIEW decision

Request

Response

Rule engine

Lifecycle events

​Outcomes

​The decision request

​The decision response

​The decision log

​Resolving a REVIEW decision

​Request

​Response

​Related

Rule engine

Lifecycle events

Outcomes

The decision request

The decision response

The decision log

Resolving a REVIEW decision

Request

Response

Related