Lifecycle Events

Ingest lifecycle event

Report a payment lifecycle event for a prior decision so Specter can keep the case and your fraud backends up to date.

Reference the decision via decision_id. Specter advances the decision’s payment state, forwards the event to the backends that participated in that decision, and stores a log entry with each backend’s delivery status. A backend that does not support the event type is reported as skipped rather than failing the request.

POST

api

events

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "data": {
    "avs_result": "match",
    "cvv_result": "match",
    "outcome": "authorized",
    "reference": "AUTH_001"
  },
  "decision_id": "9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b",
  "occurred_at": "2026-03-20T10:00:00Z",
  "type": "authorization"
}
'

{
  "id": "b7e3d2c1-4a5f-4b6c-8d9e-0f1a2b3c4d5e",
  "backend_notifications": [
    {
      "backend": "vdm",
      "error": null,
      "status": "delivered"
    }
  ],
  "data": {
    "amount": 4900,
    "currency": "EUR",
    "reason_code": "10.4",
    "stage": "first_chargeback"
  },
  "decision_id": "9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b",
  "occurred_at": "2026-03-20T10:00:00Z",
  "processed_at": "2026-03-20T10:00:01Z",
  "type": "chargeback"
}

{
  "classifier": "UNAUTHORIZED",
  "code": 401,
  "message": "No valid means of authentication was provided"
}

{
  "classifier": "FORBIDDEN",
  "code": 403,
  "message": "Not allowed to access this resource or feature"
}

{
  "classifier": "NOT_FOUND",
  "code": 404,
  "message": "The requested resource does not exist"
}

{
  "classifier": "VALIDATION_ERROR",
  "code": 422,
  "validation_errors": [
    {
      "message": "must be a positive integer",
      "path": "limit"
    }
  ]
}

Authorizations

Authorization

string

header

required

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

Body

application/json

Event request

Lifecycle event ingestion request.

data

object

required

Event-type-specific payload. The fields depend on the event type — see Lifecycle events.

decision_id

string<uuid>

required

The Specter decision this event is linked to.

Example:

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

occurred_at

string<date-time>

required

When the payment event occurred (ISO 8601).

Example:

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

type

enum<string>

required

The type of payment lifecycle event.

Available options:

authorization,

capture,

refund,

void,

chargeback,

fraud_report,

failed

Response

Event entry

Persisted lifecycle event log entry.

string<uuid>

Example:

"4a8c2e6d-7f1b-4d9a-b3e5-9c6f2a8d4e1b"

backend_notifications

object[]

Show child attributes

data

object

Event-type-specific payload. The fields depend on the event type — see Lifecycle events.

Example:

{
  "avs_result": "match",
  "cvv_result": "match",
  "outcome": "authorized",
  "reference": "AUTH_001"
}

decision_id

string<uuid>

Example:

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

occurred_at

string<date-time>

Example:

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

processed_at

string<date-time>

Example:

"2026-06-01T10:04:02Z"

type

enum<string>

Available options:

authorization,

capture,

refund,

void,

chargeback,

fraud_report,

failed

Example:

"authorization"

⌘I

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "data": {
    "avs_result": "match",
    "cvv_result": "match",
    "outcome": "authorized",
    "reference": "AUTH_001"
  },
  "decision_id": "9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b",
  "occurred_at": "2026-03-20T10:00:00Z",
  "type": "authorization"
}
'

{
  "id": "b7e3d2c1-4a5f-4b6c-8d9e-0f1a2b3c4d5e",
  "backend_notifications": [
    {
      "backend": "vdm",
      "error": null,
      "status": "delivered"
    }
  ],
  "data": {
    "amount": 4900,
    "currency": "EUR",
    "reason_code": "10.4",
    "stage": "first_chargeback"
  },
  "decision_id": "9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b",
  "occurred_at": "2026-03-20T10:00:00Z",
  "processed_at": "2026-03-20T10:00:01Z",
  "type": "chargeback"
}

{
  "classifier": "UNAUTHORIZED",
  "code": 401,
  "message": "No valid means of authentication was provided"
}

{
  "classifier": "FORBIDDEN",
  "code": 403,
  "message": "Not allowed to access this resource or feature"
}

{
  "classifier": "NOT_FOUND",
  "code": 404,
  "message": "The requested resource does not exist"
}

{
  "classifier": "VALIDATION_ERROR",
  "code": 422,
  "validation_errors": [
    {
      "message": "must be a positive integer",
      "path": "limit"
    }
  ]
}

Getting Started

Decisions

Lifecycle Events

Admin

Ingest lifecycle event

Authorizations

Body

Response