Agent Payment Events

An Agent Payment Event (APE) is one record of one thing that happened to a payment. A single payment usually produces several events, linked by payment.payment_id: for example payment.requested, then payment.authorized, then payment.settled.

The format is open (Apache-2.0) and published as JSON Schema 2020-12 at https://schema.halvorai.com/ape/v0.1.json. You can emit and store APE events without HalvorAI. See the APE schema reference.

What an event contains

{
  "ape_version": "0.1",
  "id": "evt_01JA8R2M7D0F3G6H9J2K5L8N1P",
  "type": "payment.authorized",
  "occurred_at": "2026-10-17T10:02:44.910Z",
  "environment": "test",
  "source": { "id": "src_01JA8P1A2B3C4D5E6F7G8H9J0K", "sdk": "@halvorai/ingest@0.1.0", "adapter": "stripe-issuing" },
  "agent": { "id": "agt_travel_12", "name": "Travel booking agent" },
  "owner": { "id": "own_u_4410", "type": "person", "country": "US" },
  "instruction": {
    "id": "ins_8890",
    "hash": "sha256:ba726dd8ab1c1abbad0cdc31cd2ae3be0f9ea3bec7278a738030f0157e76afad",
    "channel": "chat"
  },
  "payment": {
    "payment_id": "iauth_1QxYz2AbCdEfGh",
    "rail": "card",
    "amount": { "value": "41200", "unit": "minor", "currency": "USD" },
    "status": "authorized",
    "rail_ref": { "authorization_id": "iauth_1QxYz2AbCdEfGh", "processor": "stripe-issuing" }
  },
  "payee": { "type": "merchant", "name": "Example Airways", "mcc": "4511", "country": "US" }
}

Block	What it answers
`agent`	Which agent paid. Your own stable id for it.
`owner`	The person or business the agent acts for.
`instruction`	What the agent was asked to do. Only a hash and an optional redacted summary, never the full text.
`payment`	The rail, the amount, the status and the rail’s own identifiers.
`payee`	Who was paid. Names and wallet addresses are screened against sanctions lists.
`instrument`	The payer-side instrument: a card (last four only), a token reference, or a wallet.
`evidence`	Network proofs, attached verbatim. See evidence.
`related`	Links to a previous or corrected event, and a session id.

Event types

Type	Meaning
`payment.requested`	The agent was asked to pay. No money moved.
`payment.authorized`	Funds were authorized, or the payment was signed.
`payment.settled`	Funds moved.
`payment.failed`	Declined or failed. `payment.failure_reason` is required.
`payment.refunded`	A full or partial refund.
`payment.disputed`	A chargeback or dispute was opened.

Amounts

Amounts are decimal integer strings, never floats. unit: minor is the currency’s smallest unit with an ISO 4217 currency ("41200" is USD 412.00). unit: atomic is a token’s smallest unit with an asset that names the network, address, symbol and decimals. HalvorAI adds a US-dollar amount when it receives the event.

Signing

Every event travels in an envelope with a detached signature:

{ "event": { "...": "the event" }, "sig": "eyJhbGciOiJFZERTQSJ9..<signature>" }

The signature is a compact JWS (RFC 7515, detached payload) with alg set to EdDSA, over the RFC 8785 canonical JSON form of the event, made with your source’s Ed25519 key. The SDK does this for you. See the send events guide if you sign by hand.

Events never change

Events are append-only. If something was wrong, send a new event that points at the old one with related.corrects_event_id. The original stays, and the hash chain proves it was not edited.