> For the complete documentation index, see [llms.txt](https://developers.coincircuit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coincircuit.io/webhooks/readme/transactions.md).

# Transactions

Transaction webhook events and example payloads.

Transaction webhooks track blockchain activity for incoming payments.

Use these events to follow on-chain state before the payment is final.

### Field descriptions

Transaction webhook events use `data.transaction`.

They also include `data.session` for the related payment session.

#### Transaction object

| Field                            | Type             | Description                                          |
| -------------------------------- | ---------------- | ---------------------------------------------------- |
| `data.transaction.id`            | `string`         | Unique transaction identifier.                       |
| `data.transaction.txHash`        | `string`         | Transaction hash on the blockchain.                  |
| `data.transaction.status`        | `string`         | Transaction status. See each event below.            |
| `data.transaction.chain`         | `string`         | Blockchain network.                                  |
| `data.transaction.asset`         | `string`         | Crypto asset received.                               |
| `data.transaction.fromAddress`   | `string`         | Sender's wallet address.                             |
| `data.transaction.toAddress`     | `string`         | Destination wallet address.                          |
| `data.transaction.amount`        | `string`         | Crypto amount received.                              |
| `data.transaction.confirmations` | `number`         | Number of blockchain confirmations.                  |
| `data.transaction.failureReason` | `string \| null` | Failure reason when present.                         |
| `data.transaction.confirmedAt`   | `string \| null` | When the transaction was confirmed. Null until then. |
| `data.transaction.createdAt`     | `string`         | When the transaction was detected (ISO 8601).        |

#### Related session object

`data.session` has the same shape as in [payment events](/webhooks/readme/payments.md). `settlements` is always `null` here, because the session has not settled yet.

### Events

* `transaction.received`
* `transaction.confirmed`

### `transaction.received`

Sent when an incoming transaction is first detected on the blockchain. `data.transaction.status` is `pending`.

Use this event for early detection.

Do not treat it as final confirmation.

```json
{
  "event": "transaction.received",
  "data": {
    "transaction": {
      "id": "tx_123",
      "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "status": "pending",
      "chain": "ethereum",
      "asset": "USDT",
      "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "toAddress": "0xabcdef1234567890abcdef1234567890abcdef1234",
      "amount": "100.55",
      "confirmations": 1,
      "failureReason": null,
      "confirmedAt": null,
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    "session": {
      "id": "cs_123456789_abcdef",
      "reference": "ORDER-2024-001",
      "title": "Order #2024-001",
      "description": "Payment for premium subscription",
      "state": "open",
      "type": "payment",
      "amount": "100.00",
      "amountPaid": null,
      "currency": "USD",
      "settlements": null,
      "payment": {
        "status": "pending",
        "asset": "USDT",
        "chain": "ethereum",
        "amount": "100.55",
        "amountReceived": "0",
        "conversionRate": "1.0055",
        "gasFee": "0.05",
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "feePaidBy": "customer"
      },
      "cancelUrl": "https://example.com/cancel",
      "successUrl": "https://example.com/success",
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "customer@example.com",
        "phone": "+2348123456789",
        "firstName": "John",
        "lastName": "Doe",
        "metadata": {
          "userId": "usr_8f21c3"
        }
      },
      "metadata": {
        "orderId": "ORDER-2024-001",
        "userId": "user_123"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "expiresAt": "2024-01-15T11:30:00.000Z",
      "completedAt": null
    }
  }
}
```

### `transaction.confirmed`

Sent when a transaction reaches the required number of confirmations. `data.transaction.status` is `confirmed`.

Use this event when you need confirmed blockchain state.

```json
{
  "event": "transaction.confirmed",
  "data": {
    "transaction": {
      "id": "tx_123",
      "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "status": "confirmed",
      "chain": "ethereum",
      "asset": "USDT",
      "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "toAddress": "0xabcdef1234567890abcdef1234567890abcdef1234",
      "amount": "100.55",
      "confirmations": 12,
      "failureReason": null,
      "confirmedAt": "2024-01-15T10:35:00.000Z",
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    "session": {
      "id": "cs_123456789_abcdef",
      "reference": "ORDER-2024-001",
      "title": "Order #2024-001",
      "description": "Payment for premium subscription",
      "state": "open",
      "type": "payment",
      "amount": "100.00",
      "amountPaid": "100.00",
      "currency": "USD",
      "settlements": null,
      "payment": {
        "status": "pending",
        "asset": "USDT",
        "chain": "ethereum",
        "amount": "100.55",
        "amountReceived": "100.55",
        "conversionRate": "1.0055",
        "gasFee": "0.05",
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "feePaidBy": "customer"
      },
      "cancelUrl": "https://example.com/cancel",
      "successUrl": "https://example.com/success",
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "customer@example.com",
        "phone": "+2348123456789",
        "firstName": "John",
        "lastName": "Doe",
        "metadata": {
          "userId": "usr_8f21c3"
        }
      },
      "metadata": {
        "orderId": "ORDER-2024-001",
        "userId": "user_123"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "expiresAt": "2024-01-15T11:30:00.000Z",
      "completedAt": null
    }
  }
}
```