Ingest lifecycle event - Hellgate Cloud Platform

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. See IP-6 schema for per-type fields.

decision_id

string<uuid>

required

The Specter decision this event is linked to.

occurred_at

string<date-time>

required

When the payment event occurred (ISO 8601).

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>

backend_notifications

object[]

Show child attributes

data

object

decision_id

string<uuid>

occurred_at

string<date-time>

processed_at

string<date-time>

type

enum<string>

Available options:

authorization,

capture,

refund,

void,

chargeback,

fraud_report,

failed

Get event detailsRetrieve a persisted lifecycle event by its ID. The entry includes the event payload and the delivery status for each notified backend.

⌘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"
    }
  ]
}