Events

Every event AgentPay delivers to a registered endpoint, with the fields in data. Deliveries are JSON with id, type, created and data.

Delivery

{
  "id": "evt_card_cleared_8f2a...",
  "type": "card.cleared",
  "created": 1762182000,
  "data": { "card_id": "card_8f2a...", "card_last4": "8339", "amount": 1.98, "fees": 0, "merchant": "NAMECHEAP", "network": "visa", "balance_after": 30.98, "provider_transaction_id": "..." }
}

Cards

card.authorized

The merchant charged an issued card. The money is held; settled on the spend is still false.

Field	Type
`card_id`	string	The card.
`card_last4`	string
`amount`	number	Dollars.
`merchant`	string	The merchant name as the network reports it.
`network`	string	`visa` or `mastercard`.
`provider_transaction_id`	string	The network's transaction id.

card.cleared

The network settled a charge, usually by the next day. The wallet balance moved.

Field	Type
`card_id`, `card_last4`, `merchant`, `network`, `provider_transaction_id`		As above.
`amount`	number	The settled amount in dollars.
`fees`	number	Network fees in dollars, when any.
`balance_after`	number	The wallet balance after the charge.

card.declined

A charge on an issued card was refused.

Field	Type
`card_id`, `card_last4`, `amount`, `merchant`, `network`, `provider_transaction_id`		As above.
`decline_reason`	string	The reason. A second charge on a used single-use card is the guard working.

Checkouts

Every checkout event's data carries checkout_id, and its id is derived from it, so a redelivery has the same id.

checkout.submitted

The run paid. order_id and order_total are on the checkout read.

The run stopped at a sign-in page.

Field	Type
`login_url`	string	The page the browser stopped on. Read `login_check` and `connect_url` from `GET /v1/checkout/{id}`.

checkout.needs_card_approval

A run paying with the person's own card reached the review and waits for the cardholder.

Field	Type
`approval_url`	string	Send it to the cardholder.
`approval_expires_at`	string	When the link stops working.
`amount_display`	string	The total, e.g. `"60.90 AED"`.
`card_last4`	string

checkout.blocked

AgentPay stopped the run.

Field	Type
`reason`	string	`approval_timeout`, `engine_error`, `max_iterations`, `payment_unknown`, `site_busy`, `unreachable`, or the wall the run met.
`card_last4`	string	Only on `payment_unknown` with a connected card.

Money

money.funded

A top-up landed in the wallet.

Field	Type
`amount`	number	Dollars.
`currency`	string	`USD`.
`method`	string	`card`, `stablecoin`, `bank` or `gift`.
`rail`	string	On a bank transfer: `ach`, `wire_domestic`, `wire_international`, `uae_local`.
`reference_code`	string	On a bank transfer, the memo code it was matched by.
`funding_event_id`	string
`provider_ref`	string	Stripe's reference on a card or stablecoin top-up.
`balance_after`	number	The wallet balance after the credit.