Webhook Events

This page documents all webhook event types and their payloads.

Transaction Events

transaction.authorized

Sent when a transaction is authorized (pending hold placed).

{
  "id": "evt_abc123",
  "type": "transaction.authorized",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "transactionId": "txn_123",
    "cardId": "card_456",
    "agentId": "agent_789",
    "userId": "user_abc",
    "amount": 2500,
    "currency": "USD",
    "merchantName": "DoorDash",
    "merchantCategory": "Restaurants",
    "merchantCategoryCode": "5812",
    "status": "pending",
    "attestationStatus": "attested"
  }
}

transaction.completed

Sent when a transaction settles (funds captured).

{
  "id": "evt_abc123",
  "type": "transaction.completed",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "transactionId": "txn_123",
    "cardId": "card_456",
    "agentId": "agent_789",
    "userId": "user_abc",
    "amount": 2500,
    "authorizedAmount": 2500,
    "currency": "USD",
    "merchantName": "DoorDash",
    "status": "completed",
    "postedAt": 1703606400000
  }
}

transaction.declined

Sent when a transaction is declined.

{
  "id": "evt_abc123",
  "type": "transaction.declined",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "transactionId": "txn_123",
    "cardId": "card_456",
    "agentId": "agent_789",
    "amount": 50000,
    "currency": "USD",
    "merchantName": "Suspicious Merchant",
    "status": "declined",
    "declinedReason": "insufficient_funds"
  }
}

Decline Reasons:

insufficient_funds - Credit limit exceeded
card_frozen - Card is frozen
card_closed - Card is closed
spending_limit_exceeded - Card or agent limit exceeded
blocked_merchant - Merchant on block list
blocked_mcc - Merchant category blocked
fraud_suspected - Fraud detection triggered

transaction.reversed

Sent when a refund is processed.

{
  "id": "evt_abc123",
  "type": "transaction.reversed",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "transactionId": "txn_123",
    "cardId": "card_456",
    "originalAmount": 2500,
    "reversedAmount": 2500,
    "currency": "USD",
    "merchantName": "DoorDash",
    "status": "reversed"
  }
}

Card Events

card.created

Sent when a new card is issued.

{
  "id": "evt_abc123",
  "type": "card.created",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "cardId": "card_456",
    "agentId": "agent_789",
    "userId": "user_abc",
    "type": "single",
    "purpose": "Order dinner on DoorDash",
    "last4": "4242",
    "status": "active"
  }
}

card.frozen

Sent when a card is frozen (manually or by policy).

{
  "id": "evt_abc123",
  "type": "card.frozen",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "cardId": "card_456",
    "agentId": "agent_789",
    "reason": "manual",
    "frozenBy": "api"
  }
}

Freeze Reasons:

manual - Frozen via API
agent_suspended - Parent agent was suspended
spending_limit_exceeded - Card limit exceeded
unattested_spend - Unattested transaction detected
merchant_drift - Unexpected merchant

card.closed

Sent when a card is closed.

{
  "id": "evt_abc123",
  "type": "card.closed",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "cardId": "card_456",
    "agentId": "agent_789",
    "reason": "single_use_completed",
    "closedBy": "system"
  }
}

Close Reasons:

manual - Closed via API
single_use_completed - Single-use card after successful transaction
ttl_expired - Card TTL reached
agent_deleted - Parent agent was deleted

card.expired

Sent when a card’s TTL is reached.

{
  "id": "evt_abc123",
  "type": "card.expired",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "cardId": "card_456",
    "agentId": "agent_789",
    "ttlDays": 30,
    "createdAt": 1700928000000
  }
}

Agent Events

agent.created

Sent when a new agent is created.

{
  "id": "evt_abc123",
  "type": "agent.created",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "agentId": "agent_789",
    "userId": "user_abc",
    "name": "checkout-bot",
    "status": "active"
  }
}

agent.suspended

Sent when an agent is suspended.

{
  "id": "evt_abc123",
  "type": "agent.suspended",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "agentId": "agent_789",
    "userId": "user_abc",
    "reason": "spending_limit_exceeded",
    "suspendedBy": "system"
  }
}

agent.limit_exceeded

Sent when an agent hits its spending limit.

{
  "id": "evt_abc123",
  "type": "agent.limit_exceeded",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "agentId": "agent_789",
    "userId": "user_abc",
    "spendingLimit": 50000,
    "currentSpend": 50250,
    "frequency": "perMonth",
    "action": "suspended"
  }
}

User Events

user.application.approved

Sent when a user’s KYC application is approved.

{
  "id": "evt_abc123",
  "type": "user.application.approved",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "userId": "user_abc",
    "email": "[email protected]",
    "applicationStatus": "approved"
  }
}

user.application.denied

Sent when a user’s KYC application is denied.

{
  "id": "evt_abc123",
  "type": "user.application.denied",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "userId": "user_abc",
    "email": "[email protected]",
    "applicationStatus": "denied",
    "reason": "identity_verification_failed"
  }
}

user.balance.updated

Sent when a user’s balance changes.

{
  "id": "evt_abc123",
  "type": "user.balance.updated",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "userId": "user_abc",
    "creditLimit": 10000,
    "spendingPower": 7500,
    "pendingCharges": 1500,
    "postedCharges": 1000,
    "balanceDue": 1000
  }
}

Deposit & Withdrawal Events

deposit.received

Sent when a deposit is received.

{
  "id": "evt_abc123",
  "type": "deposit.received",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "userId": "user_abc",
    "chainId": 8453,
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": 10000,
    "transactionHash": "0x..."
  }
}

withdrawal.confirmed

Sent when a withdrawal is confirmed on-chain.

{
  "id": "evt_abc123",
  "type": "withdrawal.confirmed",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "withdrawalId": "withdrawal_xyz",
    "userId": "user_abc",
    "chainId": 8453,
    "amount": 5000,
    "recipientAddress": "0x...",
    "transactionHash": "0x..."
  }
}

3DS Events

challenge.requested

Sent when a 3DS challenge (OTP) is available.

{
  "id": "evt_abc123",
  "type": "challenge.requested",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "challengeId": "challenge_xyz",
    "cardId": "card_456",
    "transactionId": "txn_123",
    "otp": "123456",
    "expiresAt": 1703520300000,
    "deliveryMethod": "webhook"
  }
}

The OTP is included directly in the webhook payload. Use this to complete 3DS challenges in your browser automation.

Attestation Events

credential.accessed

Sent when card credentials are retrieved.

{
  "id": "evt_abc123",
  "type": "credential.accessed",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "accessEventId": "evt_xyz",
    "cardId": "card_456",
    "agentId": "agent_789",
    "exposureMode": "rawPan",
    "summary": "Order dinner on DoorDash",
    "expectedAmount": 2500
  }
}

spend.unattested

Sent when a transaction occurs without a recent attestation.

{
  "id": "evt_abc123",
  "type": "spend.unattested",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "transactionId": "txn_123",
    "cardId": "card_456",
    "agentId": "agent_789",
    "amount": 2500,
    "merchantName": "Unknown Merchant",
    "lastCredentialAccess": null
  }
}

Intent Events

intent.matched

Sent when a transaction matches an intent within tolerance.

{
  "id": "evt_abc123",
  "type": "intent.matched",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "intentId": "int_xyz",
    "customerIntentId": "order-123",
    "cardId": "card_456",
    "agentId": "agent_789",
    "transactionId": "txn_123",
    "summary": "Order lunch on DoorDash",
    "expectedAmount": 2500,
    "actualAmount": 2450,
    "expectedMerchant": "DoorDash",
    "actualMerchant": "DOORDASH",
    "matchResult": {
      "amountMatch": true,
      "merchantMatch": true
    }
  }
}

intent.mismatched

Sent when a transaction matches an intent but is outside tolerance.

{
  "id": "evt_abc123",
  "type": "intent.mismatched",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "intentId": "int_xyz",
    "customerIntentId": "order-123",
    "cardId": "card_456",
    "agentId": "agent_789",
    "transactionId": "txn_123",
    "summary": "Order lunch on DoorDash",
    "expectedAmount": 2500,
    "tolerance": 500,
    "actualAmount": 5000,
    "expectedMerchant": "DoorDash",
    "actualMerchant": "DOORDASH",
    "matchResult": {
      "amountMatch": false,
      "merchantMatch": true
    }
  }
}

A mismatched intent indicates the agent spent more (or less) than declared, or at a different merchant. Investigate for potential misuse.

intent.expired

Sent when an intent expires without a matching transaction.

{
  "id": "evt_abc123",
  "type": "intent.expired",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "intentId": "int_xyz",
    "customerIntentId": "order-123",
    "cardId": "card_456",
    "agentId": "agent_789",
    "summary": "Order lunch on DoorDash",
    "expectedAmount": 2500,
    "ttlMinutes": 30,
    "createdAt": 1703518200000,
    "expiredAt": 1703520000000
  }
}

Dispute Events

dispute.created

Sent when a chargeback is initiated.

{
  "id": "evt_abc123",
  "type": "dispute.created",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "disputeId": "dispute_xyz",
    "transactionId": "txn_123",
    "cardId": "card_456",
    "amount": 2500,
    "reason": "fraud",
    "status": "open"
  }
}

dispute.resolved

Sent when a dispute is resolved.

{
  "id": "evt_abc123",
  "type": "dispute.resolved",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "disputeId": "dispute_xyz",
    "transactionId": "txn_123",
    "amount": 2500,
    "outcome": "won",
    "status": "closed"
  }
}

Overview

​Webhook Events

​Transaction Events

​transaction.authorized

​transaction.completed

​transaction.declined

​transaction.reversed

​Card Events

​card.created

​card.frozen

​card.closed

​card.expired

​Agent Events

​agent.created

​agent.suspended

​agent.limit_exceeded

​User Events

​user.application.approved

​user.application.denied

​user.balance.updated

​Deposit & Withdrawal Events

​deposit.received

​withdrawal.confirmed

​3DS Events

​challenge.requested

​Attestation Events

​credential.accessed

​spend.unattested

​Intent Events

​intent.matched

​intent.mismatched

​intent.expired

​Dispute Events

​dispute.created

​dispute.resolved

Webhook Events

Transaction Events

transaction.authorized

transaction.completed

transaction.declined

transaction.reversed

Card Events

card.created

card.frozen

card.closed

card.expired

Agent Events

agent.created

agent.suspended

agent.limit_exceeded

User Events

user.application.approved

user.application.denied

user.balance.updated

Deposit & Withdrawal Events

deposit.received

withdrawal.confirmed

3DS Events

challenge.requested

Attestation Events

credential.accessed

spend.unattested

Intent Events

intent.matched

intent.mismatched

intent.expired

Dispute Events

dispute.created

dispute.resolved