Decisions

Create decision

Evaluate a payload and receive an ALLOW, REVIEW, or BLOCK decision. If an asynchronous backend rule is involved, the response is PROVISIONAL and updated later.

context selects the active ruleset, and the ruleset’s bound schema defines the payload. The body below is the built-in transaction schema; a context bound to a custom schema takes that schema’s fields in the same envelope. The payload validates against the schema before any rule runs — shape, required fields, and each field’s type rule — and a failure returns 422 naming the path without echoing regulated values. Below PCI level SAQ_D, a payload carrying pci-pan or pci-sad fields rejects with 422.

POST

api

decisions

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/decisions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "billing": {
    "address1": "96 Powers Street",
    "city": "Milford",
    "country": "US",
    "first_name": "James",
    "last_name": "Smith",
    "postal_code": "03055",
    "state": "NH"
  },
  "context": "checkout",
  "credential": {
    "pan": {
      "cardholder_name": "Sherlock Holmes",
      "expiry_month": 12,
      "expiry_year": 2031,
      "value": "4111111111111111"
    },
    "type": "pan"
  },
  "customer": {
    "id": "cust_001",
    "email": "sherlock@example.com",
    "first_name": "Sherlock",
    "last_name": "Holmes"
  },
  "device": {
    "fingerprint": "fp_vdm_test",
    "ip": "1.2.3.4",
    "language": "en-GB"
  },
  "items": [
    {
      "categories": [
        "Accessories",
        "Smoking"
      ],
      "name": "Calabash Pipe",
      "price": 4900,
      "product_type": "physical",
      "quantity": 1,
      "sku": "PIPE-001"
    }
  ],
  "metadata": {
    "campaign": "spring_2026",
    "channel": "web"
  },
  "shipping": {
    "carrier": "DHL",
    "method": "STANDARD"
  },
  "transaction": {
    "amount": 4900,
    "currency": "USD",
    "reference": "ord_001"
  }
}
'

{
  "id": "9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b",
  "backend_results": [],
  "context": "checkout",
  "credential_fingerprint": "crd_4ba2188f9c1e",
  "credential_type": "pan",
  "decision": "ALLOW",
  "evaluated_at": "2026-06-02T12:00:00Z",
  "events": [],
  "has_backend_error": false,
  "latency_us": 4250,
  "masked_credential": "411111 •••••• 1111",
  "resolution": null,
  "ruleset_id": "1f2e3d4c-5b6a-4978-8c0d-1e2f3a4b5c6d",
  "ruleset_version": 3,
  "source": "RULE_ENGINE",
  "triggered_rules": []
}

Authorizations

Authorization

string

header

required

HS256-signed JWT bearer token, obtained via the OAuth2 client-credentials grant (see Authentication).

Body

application/json

Decision request

credential

Full PAN · object

required

Full PAN credential. The enclosing structure stays PCI-PAN-gated by its pan-typed value field regardless of which sub-fields are populated.

Full PAN
Masked PAN
SEPA Direct Debit
PayPal

Show child attributes

customer

object

required

Show child attributes

transaction

object

required

Show child attributes

airline

Airline · object

Airline / travel industry data. Present only for airline transactions.

Show child attributes

billing

object

Billing address for the transaction

Show child attributes

context

string

Ruleset context key. Defaults to "default" if omitted.

Example:

"checkout"

device

object

Show child attributes

items

Item · object[]

Cart / order line items

A cart / order line item. At least one of name or sku is required; a line item carrying neither rejects with 422.

Item
Item

Show child attributes

Example:

{
  "categories": ["Accessories", "Smoking"],
  "name": "Calabash Pipe",
  "price": 2500,
  "product_type": "physical",
  "quantity": 1,
  "sku": "PIPE-001"
}

metadata

object

Flat key-value pairs stored alongside the decision. Available to rules as $.metadata.* and forwarded to backends, so treat it as data you share with your backend providers.

Show child attributes

Example:

{
  "campaign": "spring_2026",
  "channel": "web"
}

shipping

object

Shipping address for the transaction

Show child attributes

Response

Decision result

Result of evaluating a transaction against the active ruleset.

string<uuid>

Unique decision identifier

Example:

"1e7b9c0a-2d43-4f6a-8d29-c4a1f2d05b3e"

amount

integer | null

Example:

5000

backend_results

BackendResult · object[]

One entry per backend rule that was executed.

Show child attributes

context

string

Example:

"checkout"

credential_fingerprint

string

Deterministic HMAC-SHA256 payment credential identifier

Example:

"crd_4ba218..."

credential_type

enum<string> | null

Type of credential supplied in the request

Available options:

pan,

masked_pan,

sepa,

paypal

currency

string | null

Example:

"USD"

customer_id

string | null

Example:

"customer-123"

decision

enum<string>

BLOCK terminates on first match. REVIEW accumulates. ALLOW is the default when no rules match.

Available options:

ALLOW,

BLOCK,

REVIEW,

PROVISIONAL

device_fingerprint

string | null

pii

Example:

"fp-9c1e4b7a"

device_ip

string | null

pii

Example:

"1.2.3.4"

evaluated_at

string<date-time>

Example:

"2026-06-01T10:00:00Z"

events

object[]

Always empty on a freshly evaluated decision.

Show child attributes

has_backend_error

boolean

True if any backend_results entry carries a non-nil error (e.g. "backend_capability_disabled").

Example:

false

integration

string | null

Integration type that originated this decision (e.g. 'interceptor')

Example:

"interceptor"

interceptor_id

string<uuid> | null

ID of the interceptor that originated this decision

Example:

null

latency_us

integer

Example:

4250

masked_credential

string | null

Display-safe masked representation, e.g. '411111 •••••• 4242' for cards or 's•••@example.com' for PayPal. Identifies nobody on its own, so it carries no classification marker and is not subject to retention.

Example:

"411111 •••••• 4242"

metadata

object | null

Merchant-supplied key-value pairs stored with the decision.

Show child attributes

Example:

{ "order_ref": "X36Q9C" }

resolution

object | null

Always null on a freshly evaluated decision.

Show child attributes

ruleset_id

string<uuid> | null

Example:

"6c1f4e8b-9a2d-4c7e-b5f3-8d1a6e9c4b2f"

ruleset_version

integer | null

Example:

7

schema

SchemaBinding · object

The (schema, version) the decision was evaluated against — the resolved ruleset's binding.

Show child attributes

source

enum<string>

RULE_ENGINE — condition rules only. BACKEND — backend rule(s) only. COMBINED — both.

Available options:

RULE_ENGINE,

BACKEND,

COMBINED

transaction_reference

string | null

Example:

"X36Q9C"

triggered_rules

TriggeredRule · object[]

Show child attributes

⌘I

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/decisions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "billing": {
    "address1": "96 Powers Street",
    "city": "Milford",
    "country": "US",
    "first_name": "James",
    "last_name": "Smith",
    "postal_code": "03055",
    "state": "NH"
  },
  "context": "checkout",
  "credential": {
    "pan": {
      "cardholder_name": "Sherlock Holmes",
      "expiry_month": 12,
      "expiry_year": 2031,
      "value": "4111111111111111"
    },
    "type": "pan"
  },
  "customer": {
    "id": "cust_001",
    "email": "sherlock@example.com",
    "first_name": "Sherlock",
    "last_name": "Holmes"
  },
  "device": {
    "fingerprint": "fp_vdm_test",
    "ip": "1.2.3.4",
    "language": "en-GB"
  },
  "items": [
    {
      "categories": [
        "Accessories",
        "Smoking"
      ],
      "name": "Calabash Pipe",
      "price": 4900,
      "product_type": "physical",
      "quantity": 1,
      "sku": "PIPE-001"
    }
  ],
  "metadata": {
    "campaign": "spring_2026",
    "channel": "web"
  },
  "shipping": {
    "carrier": "DHL",
    "method": "STANDARD"
  },
  "transaction": {
    "amount": 4900,
    "currency": "USD",
    "reference": "ord_001"
  }
}
'

{
  "id": "9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b",
  "backend_results": [],
  "context": "checkout",
  "credential_fingerprint": "crd_4ba2188f9c1e",
  "credential_type": "pan",
  "decision": "ALLOW",
  "evaluated_at": "2026-06-02T12:00:00Z",
  "events": [],
  "has_backend_error": false,
  "latency_us": 4250,
  "masked_credential": "411111 •••••• 1111",
  "resolution": null,
  "ruleset_id": "1f2e3d4c-5b6a-4978-8c0d-1e2f3a4b5c6d",
  "ruleset_version": 3,
  "source": "RULE_ENGINE",
  "triggered_rules": []
}

Getting Started

Decisions

Lifecycle Events

Admin

Create decision

Authorizations

Body

Response