Via API - Hellgate Cloud Platform

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.*. Forwarded to backends and stored on the decision record, so treat it as data you share with your backend providers.

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

pan
masked_pan
sepa

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"
  }
}

First six and last four digits only — use when you do not hold the full PAN.

{
  "type": "masked_pan",
  "masked_pan": {
    "first_six": "411111",
    "last_four": "1111",
    "expiry_month": 12,
    "expiry_year": 2030,
    "scheme": "visa"
  }
}

Bank account credential for SEPA direct debit, identified by IBAN.

{
  "type": "sepa",
  "sepa": {
    "iban": "DE89370400440532013000",
    "owner_name": "John 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.

string

Unique decision identifier.

decision

string

ALLOW, REVIEW, BLOCK, or PROVISIONAL — see Outcomes. PROVISIONAL only occurs with asynchronous backend groups.

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 when the ruleset includes backend rules.

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.

The merchant requests a decision from Specter.
Specter applies all rules and, where required, reaches out to backends.
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.

The merchant requests a decision from Specter.
Specter applies all local rules and returns a PROVISIONAL result immediately.
The merchant optimistically authorizes and defers the capture.
Specter reaches out to backends asynchronously.
Specter notifies the merchant of the definitive decision through a registered webhook.
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.

​Request

​Credential types

​Example request

​Response

​Example response

​Use cases

​Synchronous pre-authorization decision

​Asynchronous decision with delayed capture

​Related

Decisions

Rule engine

Request

Credential types

Example request

Response

Example response

Use cases

Synchronous pre-authorization decision

Asynchronous decision with delayed capture

Related