Skip to main content
This reference is essential for understanding and integrating with Specter. Specter is the decision engine of the Hellgate Cloud Platform, built for pre-authorization fraud decisions and for rules over any payload you declare. Specter APIs make use of RESTful conventions where it makes sense. All calls use the standard HTTP verbs to express access semantics, like GET, POST, PATCH, and DELETE. Other related conventions are described below.

​
JSON Conventions

  • Resources are addressable by a UUID id property.
  • Property names are always in snake_case.
  • Temporal data is encoded in ISO 8601 strings.
  • Monetary amounts are integers in the minor units of the transaction currency (e.g. 14999 = €149.99).
  • Currencies are ISO 4217 codes.

​
Empty Strings and Omitted Fields

The empty string is not a value. A string field is either omitted or present with a real value — and where a field is nullable, an explicit null unsets it. Never send "". Where a field is validated as a string, "" is rejected with 422 Unprocessable Entity and a field error on that path (see Request Errors for the response format). Not every field carries that validation, so do not treat the rejection as a safety net: where it is absent, "" is accepted and then stored or forwarded verbatim — an empty string travels further into a request than a missing field ever does. In Specter, omission also shapes the evaluation itself. A field you omit — or send as null — resolves to absent in $.-path rule conditions: every predicate over it abstains, neq and not_in included, so a “not equal” rule never fires on data you never sent. An empty string or empty array counts as present. Omission also changes derived values: a masked_pan credential sent without expiry_month and expiry_year yields a different credential_fingerprint than the same card sent with them, so velocity counts and blacklist entries keyed on $.credential_fingerprint do not line up across the two.

​
Authentication

Specter authenticates every request with a signed JSON Web Token (JWT) passed as a bearer token in the Authorization header. This OAuth2 bearer scheme is the standard across the Hellgate Cloud Platform services — see Authentication.
Tokens carry scopes that gate access to individual endpoints, and are validated against your instance’s audience on each request. See Authentication for the full scope reference. Tokens must be handled with care and kept secure. Never hardcode them in your source code — keep them solely on your backend systems.

​
API Use

​
Instance URL

Specter is provided as a service of the Hellgate Cloud Platform implementing the Composable Payment Architecture (CPA). Each instance is accessible at a unique host:
{instance} is your unique instance slug and eu1 is the current environment; both are provided during onboarding.

​
Pagination

Endpoints that return lists of objects support pagination. Specter uses cursor-based pagination with the following query parameters: Example request:
The response wraps the results in data and includes a links object for paging forward:
When there are no further pages, links.next is null.

​
Request Errors

Specter uses standard HTTP status codes to indicate client errors on the API level.
The response payload for processing errors follows a standard format.
Common classifiers:

​
Security Considerations

Specter evaluates sensitive payment data and requires strict security practices:
  • All communication must use HTTPS.
  • Bearer tokens must be stored securely and never exposed to clients.
  • The full PAN supplied in a decision request is used only for evaluation and fingerprinting — it is never persisted.

​
Data Classification

Fields that carry regulated data are marked with a classification pill next to the parameter name in this reference. The marker tells you what kind of data the field holds, so you can see at a glance which parts of a payload attract handling obligations before you write any code against them. Most fields carry no marker at all. The absence of one is a statement that the field holds none of the categories above — not that the field has yet to be reviewed. Masked and truncated card numbers are the common example: 411111 •••••• 1111 identifies nobody on its own, so it carries no marker. The marker is also a gate, not just a label. Sending values into pci-pan or pci-sad fields requires your PCI DSS certification on file at SAQ-D or a full Report on Compliance (RoC). Sending personal data into pii fields requires a data processing agreement (DPA) between us. Contact support@hellgate.io to put either in place or to learn more.