order.failed

A confirm ended without a placed order. code is the gate’s reason (vault_approval_required, byoc_approval_required, sandbox_mode, per_txn_max_exceeded, …), the merchant’s (items_unavailable, pos_cart_validation, address_changed), or a refusal of the payment itself (unsupported_currency, currency_changed, no_cart). An approval pause carries approval_url and retryable: true: show the link, then send the same confirm again. A payment refusal carries retryable too, and false means the same confirm fails the same way. A failure Agentcard cannot name carries the step it stopped at, prepare or place, as code, with message null. charge_status is the only answer to whether money moved. total_cents is the US dollar amount, in cents, that Agentcard judged the confirm by. A cart priced in another currency also carries the merchant’s own figure in merchant_total_cents and merchant_currency, as on order.placed. Both merchant fields are null for a cart priced in US dollars. A confirm that failed before Agentcard priced the cart carries null in total_cents as well.

Code	What it means	What to do next
`unsupported_currency`	Agentcard cannot pay this cart in the currency it is priced in, either because Agentcard does not convert that currency or because the chosen payment source pays US dollar carts only. Nothing was charged.	Pay a Canadian dollar cart from the Vault or the balance. Any other currency needs a cart priced in US dollars.
`currency_changed`	The cart’s currency changed after Agentcard priced it. Nothing was charged.	Send the confirm again. Agentcard prices the cart again, and a Vault purchase asks the user for a fresh approval.
`no_cart`	The merchant no longer holds the cart. Nothing was charged.	Rebuild the cart, then confirm the new `hash`.

{
  "id": "evt_9f8e7d6c5b4a",
  "type": "order.failed",
  "created": 1757264400,
  "livemode": false,
  "data": {
    "order_id": null,
    "merchant": "retail",
    "merchant_name": "Amazon",
    "conversation_id": "conv_9a8b7c6d5e4f3a2b1c0d9e8f",
    "user_id": "usr_8f3k2m",
    "code": "vault_approval_required",
    "message": "This purchase needs the cardholder's approval.",
    "retryable": true,
    "approval_url": "https://vault.agentcard.sh/authorize?id=cauth_…",
    "approval_id": null,
    "approval_expires_at": null,
    "total_cents": 2306,
    "currency": "usd",
    "merchant_total_cents": null,
    "merchant_currency": null,
    "payment_source": {
      "source": "vault",
      "brand": "visa",
      "last4": "4832"
    },
    "items": null,
    "charge_status": "none"
  }
}

Webhooks

Events