Skip to main content
The blacklist lets operators block transactions based on values extracted from the decision payload — 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.
​
string
required
JSONPath matched against the decision payload (e.g. $.device.ip, $.customer.id). An entry matches one stored value against one resolved value, so the path must resolve to a scalar: array- or object-typed paths reject with 422, as do pci-pan- and pci-sad-scoped paths — an entry persists the raw value, and card blacklisting rides $.credential_fingerprint instead. Entries carry no schema binding; the check is conservative across every schema registered on your instance.
​
string
required
The exact value to block.
​
integer
Time-to-live. Omit for a permanent entry.
Manage entries with the Admin API (scopes admin:blacklist:read / admin:blacklist:write): 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.

​
Data classification and retention

Blacklist entries are a fraud-prevention record: they are exempt from the decision-record retention windows and persist indefinitely by design. ttl_seconds stays optional and merchant-set, and no sweeper runs over the table. An expired entry stops matching but its value remains in the table — a TTL does not bound retention; deleting the entry is the only erasure. Entry values are readable in clear on the Admin API and UI, including values classified as personal data — the operator who owns the blacklist must be able to inspect what is blocked and, on a data subject’s request, find and delete their entries, which a redacted or hashed value would prevent. Every read of a value classified as personal data is recorded as an audit event. To make those entries findable, every row carries a classification field on its API representation:
​
string
required
The x-data-classification that field_path resolves to across the registered schemas: any or pii. A path no schema declares is any — an omitted marker is a positive assertion, and an entry on such a path is inert anyway, since undeclared keys never enter a decision payload.
The marking is stamped when the entry is written and re-resolved whenever a schema is registered or published, so it always reflects the schemas’ current declarations rather than the ones in effect when the row was written. The reverse interaction is guarded too: a schema registration or publication that would re-classify a currently-blacklisted path as pci-pan or pci-sad is refused with 422 naming the path — never-store data cannot enter the blacklist by write, and cannot be created in place by re-declaration either.

​
Blacklist rules

A blacklist rule in a ruleset blocks any decision whose payload contains a matching value, and can auto-populate the blacklist when a configured event arrives:
​
array
JSONPath fields checked against the blacklist on each decision. Each may carry a filter pipe chain ($.customer.email | downcase()), and the same scalar and scope gates as entries apply.
​
integer
TTL applied to auto-populated entries. Omit for permanent.
​
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.