Via API

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. The context you name selects the active ruleset, and that ruleset’s schema defines the payload. The fields below are the built-in transaction schema; for a context bound to a custom schema, send the fields that schema declares in the same envelope. On the transaction schema three domains are required; everything else enriches the evaluation and is forwarded to backends where applicable.

object

required

The payment credential. type is pan, masked_pan, sepa, or paypal — see Credential types.

object

required

Must include id. May include email and date_of_birth.

object

required

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

object

ip, fingerprint, user_agent, session, and language.

object

Billing address, forwarded to applicable backends.

object

Shipping address, forwarded to applicable backends.

array

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

object

Travel data — passengers and 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 the active ruleset to evaluate — and through it, the schema.

The complete request and response schema, including every nested field, is in the API reference.

Credential types

pan
masked_pan
sepa
paypal

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,
    "schemes": ["visa"],
    "cardholder_name": "Jane Doe",
    "bin": "411111",
    "type": "credit",
    "segment": "consumer",
    "currency_code": "EUR",
    "issuer_name": "Example Bank N.A.",
    "issuer_country_code": "DE"
  }
}

The seven BIN attributes — bin, schemes, type, segment, currency_code, issuer_name, issuer_country_code — are optional and named exactly as Guardian’s metadata inquiry returns them, so you can pass that response through. Specter performs no BIN lookup of its own; rules read whatever you send.

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,
    "schemes": ["visa"],
    "bin": "411111",
    "type": "credit",
    "segment": "consumer"
  }
}

The same BIN attributes as on pan are accepted here.

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

{
  "type": "sepa",
  "sepa": {
    "iban": "DE89370400440532013000",
    "owner_name": "John Doe"
  }
}

PayPal account credential. All five fields are optional — send whichever your PayPal flow has captured at the point you call Specter. Each one you send makes the credential referenceable in more rules. As everywhere in the API, a field you don’t have a value for is omitted, never sent as "" — see Empty Strings and Omitted Fields.

{
  "type": "paypal",
  "paypal": {
    "email": "sherlock.holmes@example.com",
    "payer_id": "7E7MGXCWTTKK2",
    "address_status": "confirmed",
    "protection_eligibility": "eligible",
    "payer_status": "verified"
  }
}

All fields are caller-injected: you source them from your PayPal flow (for example Cybersource PayPal Express Checkout Services) and send them on the request. Specter performs no PayPal lookup.

Specter field	Source field	Values
`email`	`paypalCustomerEmail`	email address
`payer_id`	`paypalPayerId`	string
`address_status`	`addressStatus`	`none`, `confirmed`, `unconfirmed`
`protection_eligibility`	`protectionEligibility`	`eligible`, `partially_eligible`, `ineligible`
`payer_status`	`payerStatus`	`verified`, `unverified`

Enum values are canonical lowercase snake_case: map the source casing when you populate them (PartiallyEligible becomes partially_eligible).The fields become available at different stages of the PayPal flow, which is why none of them is mandatory. payer_id, email, address_status, and payer_status are returned once the customer approves at PayPal, while protection_eligibility is only returned after authorization — so a pre-authorization decision usually cannot carry it.Send payer_id whenever you have it: it is the source of the credential fingerprint, so a decision without it has no $.credential_fingerprint, and velocity rules and blacklist entries keyed on that path will not apply to it.The email is PII and is never persisted raw. The decision log keeps only the credential fingerprint and a masked form of the email such as s•••@example.com.

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.

string

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

string

The ruleset context that was evaluated.

object

The (name, version) the decision was evaluated against — the binding of the ruleset that served it.

string

The ruleset that served the decision.

integer

The exact version pinned to the decision.

string

Deterministic HMAC-SHA256 identifier for the payment credential. For paypal it is computed from the payer_id.

string

The credential type supplied — pan, masked_pan, sepa, or paypal.

string

Display-safe masked representation, e.g. 411111 •••••• 4242 for cards or s•••@example.com for PayPal.

array

Rules that fired, in evaluation order.

array

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

object

null until a REVIEW decision is closed — see Resolving a REVIEW decision.

Example response

{
  "id": "dec_01J...",
  "decision": "REVIEW",
  "context": "checkout",
  "schema": { "name": "transaction" },
  "ruleset_id": "7c9e6679-...",
  "ruleset_version": 3,
  "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.

Getting Started

Concepts

Integration Patterns

Request

Credential types

Example request

Response

Example response

Use cases

Synchronous pre-authorization decision

Asynchronous decision with delayed capture

Decisions

Rule engine

​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