> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cashweb.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Events

> Complete event catalog and payload contract for partner webhook consumers.

## Event Types

* `transaction.created`
* `deposit.detected`
* `deposit.confirmed`
* `transaction.completed`
* `transaction.failed`
* `transaction.expired`
* `transaction.cancelled`
* `transaction.refunded`
* `payout.settled`

## Common `data` Fields

Most events include:

* `id` / `transaction_id`
* `status`
* `crypto_currency`
* `crypto_amount`
* `rate`
* `amount`
* `network`
* `merchant_reference`
* `merchant_id`
* `terminal_id`
* `expires_at`

## Event-Specific Fields

* `transaction.created`: includes `deposit_address`.
* `deposit.detected`: includes `deposit_id`.
* `deposit.confirmed`: includes `deposit_id`.
* `payout.settled`: includes `payout_amount`, `payout_currency`.

## Payload Examples

### transaction.created

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "transaction.created",
  "data": {
    "transaction_id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "status": "awaiting_deposit",
    "crypto_currency": "usdt",
    "crypto_amount": "100.00",
    "rate": "1615.00",
    "amount": "161500.00",
    "network": "trc20",
    "deposit_address": "TXyz1234567890abcdef1234567890abcd",
    "merchant_reference": "order-4551",
    "merchant_id": "mrc_001",
    "terminal_id": "term_01",
    "expires_at": "2026-02-12T12:30:00Z"
  }
}
```

### deposit.detected

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "type": "deposit.detected",
  "data": {
    "transaction_id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "status": "deposit_confirming",
    "crypto_currency": "usdt",
    "crypto_amount": "100.00",
    "rate": "1615.00",
    "amount": "161500.00",
    "network": "trc20",
    "deposit_id": "dep_abc123",
    "merchant_reference": "order-4551",
    "merchant_id": "mrc_001",
    "terminal_id": "term_01"
  }
}
```

### deposit.confirmed

```json theme={null}
{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "type": "deposit.confirmed",
  "data": {
    "transaction_id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "status": "selling_crypto",
    "crypto_currency": "usdt",
    "crypto_amount": "100.00",
    "rate": "1615.00",
    "amount": "161500.00",
    "network": "trc20",
    "deposit_id": "dep_abc123",
    "merchant_reference": "order-4551",
    "merchant_id": "mrc_001",
    "terminal_id": "term_01"
  }
}
```

### transaction.completed

```json theme={null}
{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "type": "transaction.completed",
  "data": {
    "transaction_id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "status": "completed",
    "crypto_currency": "usdt",
    "crypto_amount": "100.00",
    "rate": "1615.00",
    "amount": "161500.00",
    "network": "trc20",
    "merchant_reference": "order-4551",
    "merchant_id": "mrc_001",
    "terminal_id": "term_01"
  }
}
```

### transaction.failed

```json theme={null}
{
  "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "type": "transaction.failed",
  "data": {
    "transaction_id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "status": "failed",
    "crypto_currency": "usdt",
    "crypto_amount": "100.00",
    "rate": "1615.00",
    "amount": "161500.00",
    "network": "trc20",
    "merchant_reference": "order-4551",
    "merchant_id": "mrc_001",
    "terminal_id": "term_01"
  }
}
```

### transaction.expired

```json theme={null}
{
  "id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "type": "transaction.expired",
  "data": {
    "transaction_id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "status": "expired",
    "crypto_currency": "usdt",
    "crypto_amount": "100.00",
    "rate": "1615.00",
    "amount": "161500.00",
    "network": "trc20",
    "merchant_reference": "order-4551",
    "merchant_id": "mrc_001",
    "terminal_id": "term_01",
    "expires_at": "2026-02-12T12:30:00Z"
  }
}
```

### transaction.cancelled

```json theme={null}
{
  "id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
  "type": "transaction.cancelled",
  "data": {
    "transaction_id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "status": "cancelled",
    "crypto_currency": "usdt",
    "crypto_amount": "100.00",
    "rate": "1615.00",
    "amount": "161500.00",
    "network": "trc20",
    "merchant_reference": "order-4551",
    "merchant_id": "mrc_001",
    "terminal_id": "term_01"
  }
}
```

### transaction.refunded

```json theme={null}
{
  "id": "b8c9d0e1-f2a3-4567-bcde-678901234567",
  "type": "transaction.refunded",
  "data": {
    "transaction_id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "status": "refunded",
    "crypto_currency": "usdt",
    "crypto_amount": "100.00",
    "rate": "1615.00",
    "amount": "161500.00",
    "network": "trc20",
    "merchant_reference": "order-4551",
    "merchant_id": "mrc_001",
    "terminal_id": "term_01"
  }
}
```

### payout.settled

```json theme={null}
{
  "id": "c9d0e1f2-a3b4-5678-cdef-789012345678",
  "type": "payout.settled",
  "data": {
    "transaction_id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "status": "completed",
    "crypto_currency": "usdt",
    "crypto_amount": "100.00",
    "rate": "1615.00",
    "amount": "161500.00",
    "network": "trc20",
    "payout_amount": "161500.00",
    "payout_currency": "NGN",
    "merchant_reference": "order-4551",
    "merchant_id": "mrc_001",
    "terminal_id": "term_01"
  }
}
```

## Notes for Consumers

* Do not assume every field is always present; handle optional fields safely.
* Use `transaction_id` + `merchant_reference` for reconciliation joins.
* `payout.settled` is emitted for payout-enabled partner share settlements.