Skip to main content
The blacklist lets operators block transactions based on values extracted from the decision context — a card fingerprint, a device IP, a customer ID, and so on. Entries can be created manually through the Admin API or populated automatically from lifecycle events.

​
Entries

A blacklist entry blocks a specific value at a given JSONPath, optionally with an expiry. 
{
  "field_path": "$.credential_fingerprint",
  "value": "crd_4ba218...",
  "ttl_seconds": 604800
}
​
field_path
string
required
JSONPath matched against the decision context (e.g. $.device.ip, $.customer.id).
​
value
string
required
The exact value to block.
​
ttl_seconds
integer
Time-to-live. Omit for a permanent entry.
Manage entries with the Admin API (scopes admin:blacklist:read / admin:blacklist:write):
MethodPath
GET/api/admin/blacklist
GET/api/admin/blacklist/{id}
POST/api/admin/blacklist
DELETE/api/admin/blacklist/{id}
For card-fingerprint entries, Specter stores a masked-PAN display_hint (e.g. ****1234) alongside the opaque fingerprint so operators can identify the card without exposing it.

​
Blacklist rules

A blacklist rule in a ruleset blocks any decision whose context contains a matching value, and can auto-populate the blacklist when a configured event arrives: 
{
  "id": "block-known-cards",
  "type": "blacklist",
  "name": "Block known fraudulent credentials",
  "action": "BLOCK",
  "enabled": true,
  "fields": ["$.credential_fingerprint", "$.device.ip"],
  "ttl_seconds": 604800,
  "populate_on": ["fraud_report", "chargeback"]
}
​
fields
array
JSONPath fields checked against the blacklist on each decision.
​
ttl_seconds
integer
TTL applied to auto-populated entries. Omit for permanent.
​
populate_on
array
Event types that trigger auto-population: fraud_report, chargeback, failed. Defaults to ["fraud_report"].
When a matching lifecycle event is ingested, Specter upserts blacklist entries for every configured field using the originating decision’s values. A card that charges back is then blocked on its next attempt.

Lifecycle events

The events that drive blacklist auto-population.