> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mitu.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mitu.ai/_mcp/server.

# Events

Events describe activity that has already happened in Mitu. Your application can receive them through webhooks to update internal records, notify customers, reconcile payments or react to wallet activity.

Every event uses the same top-level envelope. The contents of `event_data` depend on the event type.

```json
{
  "event": "wallet.debited",
  "event_id": "evt_h9x2ez72ichll2ti80cc",
  "event_created_at": "2026-09-11T18:01:41.255Z",
  "event_data": {}
}
```

### Event envelope

| Field              | Type     | Description                                                            |
| ------------------ | -------- | ---------------------------------------------------------------------- |
| `event`            | `string` | The event type, such as `payment.completed` or `wallet.credited`.      |
| `event_id`         | `string` | The unique event identifier. Use it to deduplicate webhook deliveries. |
| `event_created_at` | `string` | When the event was created.                                            |
| `event_data`       | `object` | Event-specific data associated with the activity.                      |

When customer context is present, `customer_id` identifies the Mitu customer and `customer_ref` carries the reference associated with that customer in your own system.

## Event categories

The main distinction is between money your business receives and money belonging to customers through Agent Wallets.

`payment.*` events describe payments received by your business. `wallet.*` events describe activity on Agent Wallets issued to customers. These are separate perspectives on money movement and should not be treated as interchangeable.

| Category      | Events                                                                                                            |
| ------------- | ----------------------------------------------------------------------------------------------------------------- |
| Customers     | `customer.created`                                                                                                |
| Agent Wallets | `wallet.created`, `wallet.credited`, `wallet.debited`, `wallet.frozen`, `wallet.unfrozen`                         |
| Payments      | `payment.completed`, `payment.failed`                                                                             |
| Payment links | `link.created`, `link.viewed`                                                                                     |
| Sessions      | `session.opened`, `session.closed`                                                                                |
| Invoices      | `invoice.created`, `invoice.sent`, `invoice.viewed`, `invoice.overdue`, `invoice.paid`                            |
| Subscriptions | `plan.created`, `subscription.created`, `subscription.charged`, `subscription.past_due`, `subscription.cancelled` |

## `payment.completed`

`payment.completed` is emitted when your business successfully receives a payment.

```json
{
  "event": "payment.completed",
  "event_id": "evt_er5sbax1m3vitp5d6thi",
  "event_created_at": "2026-09-09T19:03:28.154Z",
  "event_data": {
    "source": "mcp",
    "service_id": "svc_dhydwg80dzb4vy6xjl2m",
    "endpoint_id": "ep_j7z4sqeiyqu7p4ljlg4s",
    "request_path": "/orders",
    "customer_id": "cus_0t9549fps3xd",
    "customer_ref": "auth0|68f3c2a1b9",
    "amount_paid": "0.035000",
    "currency": "USDC",
    "payment_method": "x402",
    "network": "base",
    "transaction_id": "f5533e85-16d8-4f58-ba22-86dba59c6a15",
    "tx_hash": "0xfe093b9a57695615cc453f86b2890eb70e0a2860ce040f54af7aca03ce2a89ab",
    "reference": "ORDER-8841",
    "delivered": true
  }
}
```

The fields present depend on the source of the payment. For example, an MCP payment can include endpoint information, while a payment created through a payment experience can include the corresponding payment resource instead.

`delivered` indicates whether the paid request was successfully fulfilled by your API after payment. A completed payment and successful fulfilment are separate states, so `delivered: false` can mean your business has received the money even though the downstream operation did not complete successfully.

```json
{
  "delivered": false,
  "failure_status": 401
}
```

See [Agent payments](/platform/payments/agent-payments) for handling payments where settlement completed but fulfilment did not.

## `payment.failed`

`payment.failed` is emitted when a payment attempt does not complete successfully.

```json
{
  "event": "payment.failed",
  "event_id": "evt_c9q4zx1lkm3npv8h",
  "event_created_at": "2026-09-09T18:50:29.612Z",
  "event_data": {
    "source": "mcp",
    "service_id": "svc_dhydwg80dzb4vy6xjl2m",
    "endpoint_id": "ep_j7z4sqeiyqu7p4ljlg4s",
    "request_path": "/orders",
    "customer_id": "cus_0t9549fps3xd",
    "customer_ref": "auth0|68f3c2a1b9",
    "amount": "0.035000",
    "currency": "USDC",
    "payment_method": "x402",
    "network": "base",
    "transaction_id": "b01506f6-5f13-4197-b916-4066ef95c1d8",
    "reason": "settlement_failed",
    "detail": "insufficient balance to perform useroperation: precheck failed"
  }
}
```

| Reason                 | Meaning                                                                |
| ---------------------- | ---------------------------------------------------------------------- |
| `no_supported_method`  | No supported payment method could be used.                             |
| `insufficient_balance` | The payer did not have enough available balance.                       |
| `over_limit`           | The payment could not proceed within the applicable spending controls. |
| `settlement_failed`    | The underlying payment settlement did not complete.                    |
| `upstream_rejected`    | The upstream payment operation was rejected.                           |

## `wallet.created`

`wallet.created` is emitted when an Agent Wallet is created for a customer.

```json
{
  "event": "wallet.created",
  "event_id": "evt_gezy2oi5cegdablsyi3p",
  "event_created_at": "2026-09-11T00:32:58.292Z",
  "event_data": {
    "customer_id": "cus_xsfod4ihhn9t",
    "customer_ref": "goro_user_9100",
    "wallet_id": "wal_65286515b43d4e3eba93",
    "name": "Travel",
    "currency": "USDC",
    "limits": {
      "per_payment": 25,
      "session": 50,
      "daily": 100,
      "monthly": 200,
      "approve_above": 50,
      "currency": "USD"
    },
    "addresses": [
      {
        "network": "base",
        "address": "0xa90818aeC6..."
      },
      {
        "network": "tempo",
        "address": "0xa90818aeC6..."
      },
      {
        "network": "solana",
        "address": "7U6P9CrM7C..."
      }
    ]
  }
}
```

This event describes a wallet that has come into existence. Wallet creation is idempotent, so a repeated creation request that returns an existing wallet does not raise another `wallet.created` event.

## `wallet.credited`

`wallet.credited` is emitted when funds are credited to an Agent Wallet and become part of its available balance.

```json
{
  "event": "wallet.credited",
  "event_id": "evt_u0b5zq2xlk8mpn1k",
  "event_created_at": "2026-09-09T18:41:50.204Z",
  "event_data": {
    "customer_id": "cus_0t9549fps3xd",
    "customer_ref": "auth0|68f3c2a1b9",
    "wallet_id": "wal_65286515b43d4e3eba93",
    "amount": "0.067000",
    "currency": "USDC",
    "network": "base",
    "address": "0xCD2CEd9732...",
    "tx_hash": "0x7c1e4a902f6b...",
    "balance_after": "0.067000"
  }
}
```

`balance_after` represents the balance of that Agent Wallet rather than a combined balance across every wallet belonging to the customer.

## `wallet.debited`

`wallet.debited` is emitted when funds leave an Agent Wallet.

```json
{
  "event": "wallet.debited",
  "event_id": "evt_j3g8zq6xlk1mpv2l",
  "event_created_at": "2026-09-09T19:03:28.480Z",
  "event_data": {
    "customer_id": "cus_0t9549fps3xd",
    "customer_ref": "auth0|68f3c2a1b9",
    "amount": "0.035000",
    "currency": "USDC",
    "network": "base",
    "reason": "payment",
    "destination": {
      "type": "merchant",
      "name": "AgentPizza",
      "address": "0x1DDb114B971E67241B3aF19C958a01EBBfb1B6DD"
    },
    "transaction_id": "f5533e85-16d8-4f58-ba22-86dba59c6a15",
    "tx_hash": "0xfe093b9a57695615cc453f86b2890eb70e0a2860ce040f54af7aca03ce2a89ab",
    "delivered": true
  }
}
```

| Field              | Values                              |
| ------------------ | ----------------------------------- |
| `reason`           | `payment`, `withdrawal`, `reversal` |
| `destination.type` | `merchant`, `external`              |

When one of your own Agent Wallet customers pays your business, a `wallet.debited` event describes the wallet side while `payment.completed` describes the payment received by your business. Treat them as separate event records representing different sides of the same movement, and use `tx_hash` when you need to associate the two. Their `transaction_id` values differ because each event identifies a record in a different system.

## `wallet.frozen`

`wallet.frozen` is emitted when an Agent Wallet is frozen with [Freeze a wallet](/api-reference/agent-wallets/freeze-wallet). The agent's payments from it are refused until it is unfrozen; deposits still credit.

```json
{
  "event": "wallet.frozen",
  "event_id": "evt_p4c7zq9xlk2mrn5d",
  "event_created_at": "2026-10-29T14:05:11.402Z",
  "event_data": {
    "customer_id": "cus_0t9549fps3xd",
    "wallet_id": "wal_65286515b43d4e3eba93",
    "frozen_at": "2026-10-29T14:05:11.402Z",
    "frozen_reason": "Customer asked to pause agent spending"
  }
}
```

Freezing a wallet that is already frozen does not raise another `wallet.frozen` event.

## `wallet.unfrozen`

`wallet.unfrozen` is emitted when a frozen Agent Wallet is unfrozen and the agent may spend from it again.

```json
{
  "event": "wallet.unfrozen",
  "event_id": "evt_r8d2zq4xlk7mtn1f",
  "event_created_at": "2026-10-29T16:20:44.019Z",
  "event_data": {
    "customer_id": "cus_0t9549fps3xd",
    "wallet_id": "wal_65286515b43d4e3eba93"
  }
}
```

## Payment link events

`link.created` is emitted when a payment link is created and can include the reference and payer entry points associated with the link.

```json
{
  "event": "link.created",
  "event_id": "evt_3lp8zq1xkm6vcd2b",
  "event_created_at": "2026-09-09T14:05:11.402Z",
  "event_data": {
    "payment_link_id": "pay_n8d7piu1yc6h",
    "type": "charge",
    "amount": "25.00",
    "currency": "USD",
    "reference": "ORDER-8841",
    "description": "Two large pizzas",
    "url": {
      "checkout": "https://mitu.ai/pay/pay_n8d7piu1yc6h",
      "agent": "https://api.mitu.ai/pay/pay_n8d7piu1yc6h"
    }
  }
}
```

`link.viewed` can be used when your application needs to know that a hosted checkout was opened.

## Invoice and subscription events

Invoices and subscriptions have their own lifecycle events so your backend can react to billing state changes without polling every resource continuously.

| Resource      | Events                                                                                                            |
| ------------- | ----------------------------------------------------------------------------------------------------------------- |
| Invoices      | `invoice.created`, `invoice.sent`, `invoice.viewed`, `invoice.overdue`, `invoice.paid`                            |
| Subscriptions | `plan.created`, `subscription.created`, `subscription.charged`, `subscription.past_due`, `subscription.cancelled` |
| Sessions      | `session.opened`, `session.closed`                                                                                |

> **Events not currently emitted**
>
> `refund.completed`, `settlement.completed` and `customer.status.changed` exist in the underlying event model but are not currently emitted. Do not build application logic that depends on an event until it is listed as supported in this documentation.

## Invoice events

Every invoice event describes the invoice and who it is addressed to.

| Event             | Emitted when                                                   | Extra fields |
| ----------------- | -------------------------------------------------------------- | ------------ |
| `invoice.created` | An invoice is created.                                         | None         |
| `invoice.sent`    | An invoice is sent, including each reminder.                   | `emailed`    |
| `invoice.viewed`  | The recipient first opens the invoice's pay URL. Emitted once. | `viewed_at`  |
| `invoice.overdue` | The due date passes on a `sent` or `viewed` invoice.           | `due_at`     |

```json
{
  "event": "invoice.sent",
  "event_id": "evt_m2k7zq5xlk9prn3c",
  "event_created_at": "2026-09-11T15:04:12.330Z",
  "event_data": {
    "invoice_id": "inv_4k2m9x7ptw3c",
    "invoice_number": "INV-2026-0041",
    "amount": "1500.00",
    "currency": "USD",
    "recipient": {
      "id": "rcp_ds9hazr8jd3l",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "phone": "+2348012345678",
      "reference": "user_42"
    },
    "emailed": true
  }
}
```

| Field            | Description                                                                                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invoice_id`     | The invoice the event describes.                                                                                                                                                          |
| `invoice_number` | Your invoice number, or `null`.                                                                                                                                                           |
| `amount`         | The invoice total, as a decimal string.                                                                                                                                                   |
| `currency`       | The invoice currency.                                                                                                                                                                     |
| `recipient`      | The [recipient](/platform/payments/recipients) the invoice is addressed to: `id`, `name`, `email`, `phone` and `reference`. Use `reference` to tell whose recipient it is in your system. |
| `emailed`        | `invoice.sent` only. Whether the invoice was emailed. `false` when the recipient has no email address, so you share the link yourself.                                                    |
| `viewed_at`      | `invoice.viewed` only. When the recipient first opened the invoice.                                                                                                                       |
| `due_at`         | `invoice.overdue` only. The due date that passed.                                                                                                                                         |

An overdue invoice can still be paid. See [Invoices](/platform/payments/invoices#invoice-lifecycle).

## `invoice.paid`

`invoice.paid` is emitted when an invoice is paid. `payment.completed` is emitted for the same payment with the same `event_data`, with `source` set to `invoice`.

```json
{
  "event": "invoice.paid",
  "event_id": "evt_t6n1zq8xlk3prv7b",
  "event_created_at": "2026-09-12T09:30:51.774Z",
  "event_data": {
    "source": "invoice",
    "invoice_id": "inv_4k2m9x7ptw3c",
    "invoice_number": "INV-2026-0041",
    "recipient": {
      "id": "rcp_ds9hazr8jd3l",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "phone": "+2348012345678",
      "reference": "user_42"
    },
    "type": "charge",
    "amount_paid": "1500.00",
    "currency": "USD",
    "payment_method": "x402",
    "network": "base",
    "transaction_id": "txn_8q2w5e7r9t1y3u5i7o9p",
    "tx_hash": "0x3b9d1f7a2c6e..."
  }
}
```

## Related

#### [Webhooks](/platform/webhooks/overview)

Configure delivery, verification and retry handling.

#### [Agent payments](/platform/payments/agent-payments)

Understand the payment lifecycle behind payment events.

#### [Agent Wallets](/platform/agent-wallets/overview)

Understand the wallet resources behind wallet events.