> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Via API

> Call Specter before authorization and act on the decision outcome.

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.

<ParamField body="credential" type="object" required>
  The payment credential. `type` is `pan`, `masked_pan`, or `sepa` — see
  [Credential types](#credential-types).
</ParamField>

<ParamField body="customer" type="object" required>
  Must include `id`. May include `email` and `date_of_birth`.
</ParamField>

<ParamField body="transaction" type="object" required>
  `reference`, `amount` (minor units), and `currency` (ISO 4217).
</ParamField>

<ParamField body="device" type="object">
  `ip`, `fingerprint`, `user_agent`, `session`, and `language`.
</ParamField>

<ParamField body="billing" type="object">
  Billing address, forwarded to applicable backends.
</ParamField>

<ParamField body="shipping" type="object">
  Shipping address, forwarded to applicable backends.
</ParamField>

<ParamField body="items" type="array">
  Cart line items; each requires at least `name` or `sku`.
</ParamField>

<ParamField body="airline" type="object">
  Travel data — passengers and legs — forwarded to backends that consume it.
</ParamField>

<ParamField body="metadata" type="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.
</ParamField>

<ParamField body="context" type="string" default="default">
  Selects the active ruleset to evaluate.
</ParamField>

<Info>
  The complete request and response schema, including every nested field, is in
  the [API
  reference](/products/specter/api-reference/decisions/evaluate-transaction).
</Info>

### Credential types

<Tabs>
  <Tab title="pan">
    Full card number. Used to evaluate the transaction and compute the credential fingerprint; **never persisted**.

    ```json theme={null}
    {
      "type": "pan",
      "pan": {
        "value": "4111111111111111",
        "expiry_month": 12,
        "expiry_year": 2030,
        "scheme": "visa",
        "cardholder_name": "Jane Doe"
      }
    }
    ```
  </Tab>

  <Tab title="masked_pan">
    First six and last four digits only — use when you do not hold the full PAN.

    ```json theme={null}
    {
      "type": "masked_pan",
      "masked_pan": {
        "first_six": "411111",
        "last_four": "1111",
        "expiry_month": 12,
        "expiry_year": 2030,
        "scheme": "visa"
      }
    }
    ```
  </Tab>

  <Tab title="sepa">
    Bank account credential for SEPA direct debit, identified by IBAN.

    ```json theme={null}
    {
      "type": "sepa",
      "sepa": {
        "iban": "DE89370400440532013000",
        "owner_name": "John Doe"
      }
    }
    ```
  </Tab>
</Tabs>

### Example request

```bash theme={null}
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.

<ResponseField name="id" type="string">
  Unique decision identifier.
</ResponseField>

<ResponseField name="decision" type="string">
  `ALLOW`, `REVIEW`, `BLOCK`, or `PROVISIONAL` — see
  [Outcomes](/products/specter/concepts/decisions#outcomes). `PROVISIONAL` only occurs with asynchronous backend
  groups.
</ResponseField>

<ResponseField name="context" type="string">
  The ruleset context that was evaluated.
</ResponseField>

<ResponseField name="credential_fingerprint" type="string">
  Deterministic HMAC-SHA256 identifier for the card instrument.
</ResponseField>

<ResponseField name="credential_type" type="string">
  The credential type supplied — `pan`, `masked_pan`, or `sepa`.
</ResponseField>

<ResponseField name="masked_credential" type="string">
  Display-safe masked representation, e.g. `411111 ****** 4242`.
</ResponseField>

<ResponseField name="triggered_rules" type="array">
  Rules that fired, in evaluation order.
</ResponseField>

<ResponseField name="backend_results" type="array">
  One entry per backend rule executed, including any error such as
  `insufficient_context`. Present when the ruleset includes backend rules.
</ResponseField>

<ResponseField name="resolution" type="object">
  `null` until a `REVIEW` decision is closed — see
  [Resolving a REVIEW decision](/products/specter/concepts/decisions#resolving-a-review-decision).
</ResponseField>

### Example response

```json theme={null}
{
  "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.

```mermaid theme={null}
sequenceDiagram
    participant M as Merchant
    participant S as Specter
    participant B as Risk backend
    participant A as Acquirer
    M->>S: POST /api/decisions
    S->>B: Evaluate (rules + backends)
    B-->>S: Result
    S-->>M: ALLOW / REVIEW / BLOCK
    M->>A: Authorize
```

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.

```mermaid theme={null}
sequenceDiagram
    participant M as Merchant
    participant S as Specter
    participant B as Risk backend
    participant A as Acquirer
    M->>S: POST /api/decisions
    S-->>M: PROVISIONAL (local rules)
    M->>A: Authorize, defer capture
    S->>B: Evaluate backends (async)
    B-->>S: Result
    S-->>M: Webhook: final decision
    M->>A: Capture or cancel
```

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](/products/specter/api-reference/webhooks/register-webhook).
6. The merchant captures or cancels the authorization based on the final decision.

## Related

<CardGroup cols={2}>
  <Card title="Decisions" icon="check-double" href="/products/specter/concepts/decisions#resolving-a-review-decision">
    Outcomes, the decision log, and resolving REVIEW decisions.
  </Card>

  <Card title="Rule engine" icon="sliders" href="/products/specter/concepts/rule-engine">
    How your request is evaluated into a decision.
  </Card>
</CardGroup>