Events | Mitu API Documentation

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.

{
  "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.

{
  "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.

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

See 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.

{
  "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.

{
  "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.

{
  "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.

{
  "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. The agent’s payments from it are refused until it is unfrozen; deposits still credit.

{
  "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.

{
  "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.

{
  "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`

{
  "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 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.

`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.

{
  "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..."
  }
}

Webhooks

Configure delivery, verification and retry handling.

Agent payments

Understand the payment lifecycle behind payment events.

Agent Wallets

Understand the wallet resources behind wallet events.

Event envelope

Event categories

payment.completed

payment.failed

wallet.created

wallet.credited

wallet.debited

wallet.frozen

wallet.unfrozen