Skip to main content
In the API pattern your system calls Specter directly, reads the outcome, and decides how to proceed. You own the flow and choose exactly what context to send.

​
Request

Send POST /api/decisions with the decisions:create scope. Three domains are required; everything else enriches the evaluation and is forwarded to backends where applicable.
​
credential
object
required
The payment credential. type is pan, masked_pan, or sepa — see Credential types.
​
customer
object
required
Must include id. May include email and date_of_birth.
​
transaction
object
required
reference, amount (minor units), and currency (ISO 4217).
​
device
object
ip, fingerprint, user_agent, session, and language.
​
billing
object
Billing address, forwarded to applicable backends.
​
shipping
object
Shipping address, forwarded to applicable backends.
​
items
array
Cart line items; each requires at least name or sku.
​
airline
object
Travel data — passengers and 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 the active ruleset to evaluate.
The complete request and response schema, including every nested field, is in the API reference.

​
Credential types

Full card number. Used to evaluate the transaction and compute the credential fingerprint; never persisted.
{
  "type": "pan",
  "pan": {
    "value": "4111111111111111",
    "expiry_month": 12,
    "expiry_year": 2030,
    "scheme": "visa",
    "cardholder_name": "Jane Doe"
  }
}

​
Example request

curl -X POST https://{instance}.eu1.on-hellgate.cloud/api/decisions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "credential": { "type": "pan", "pan": { "value": "4111111111111111", "expiry_month": 12, "expiry_year": 2030 } },
    "customer": { "id": "cust_789", "email": "customer@example.com" },
    "transaction": { "reference": "order-12345", "amount": 14999, "currency": "EUR" },
    "context": "checkout"
  }'

​
Response

Specter returns the decision together with the rules that fired and any backend results.
​
id
string
Unique decision identifier.
​
decision
string
ALLOW, REVIEW, BLOCK, or PROVISIONAL — see Outcomes. PROVISIONAL only occurs with asynchronous backend groups (Specter Connect).
​
context
string
The ruleset context that was evaluated.
​
credential_fingerprint
string
Deterministic HMAC-SHA256 identifier for the card instrument.
​
credential_type
string
The credential type supplied — pan, masked_pan, or sepa.
​
masked_credential
string
Display-safe masked representation, e.g. 411111 ****** 4242.
​
triggered_rules
array
Rules that fired, in evaluation order.
​
backend_results
array
One entry per backend rule executed, including any error such as insufficient_context. Present only on Specter Connect.
​
resolution
object
null until a REVIEW decision is closed — see Resolving a REVIEW decision.

​
Example response

{
  "id": "dec_01J...",
  "decision": "REVIEW",
  "context": "checkout",
  "credential_fingerprint": "crd_4ba218...",
  "credential_type": "pan",
  "masked_credential": "411111 ****** 1111",
  "triggered_rules": [
    { "id": "ravelin-assessment", "type": "backend", "action": "REVIEW" }
  ],
  "backend_results": [{ "backend": "link-prod/ravelin", "decision": "REVIEW" }],
  "resolution": null
}

​
Use cases

​
Synchronous pre-authorization decision

Specter returns a definitive decision in one call. Simplest to integrate, and the right default when the added latency of any backends is acceptable.
  1. The merchant requests a decision from Specter.
  2. Specter applies all rules and, where required, reaches out to backends.
  3. The merchant uses the definitive result to authorize the payment.

​
Asynchronous decision with delayed capture

For latency-sensitive flows, Specter returns a fast PROVISIONAL result from local rules and finishes the backend evaluation in the background. The merchant authorizes optimistically and defers the capture until the final decision arrives.
  1. The merchant requests a decision from Specter.
  2. Specter applies all local rules and returns a PROVISIONAL result immediately.
  3. The merchant optimistically authorizes and defers the capture.
  4. Specter reaches out to backends asynchronously.
  5. Specter notifies the merchant of the definitive decision through a registered webhook.
  6. The merchant captures or cancels the authorization based on the final decision.

Decisions

Outcomes, the decision log, and resolving REVIEW decisions.

Rule engine

How your request is evaluated into a decision.