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

# Settlements

> Monitor and verify on-chain payment settlements for your invoices.

# Settlements API

Settlements represent on-chain payment confirmations. Invoica uses dual settlement detection (poll-based and event-driven) to ensure reliable payment verification.

## Settlement Lifecycle

```
PENDING → CONFIRMING → CONFIRMED → SETTLED
                          ↓
                       FAILED
```

| Status       | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| `pending`    | Payment submitted, awaiting blockchain confirmation         |
| `confirming` | Transaction found, waiting for required block confirmations |
| `confirmed`  | Required confirmations reached                              |
| `settled`    | Settlement finalized, invoice updated                       |
| `failed`     | Transaction reverted or timed out                           |

## How Settlement Detection Works

### Poll-Based

A background worker checks the blockchain every 15 seconds:

```
For each pending settlement:
  → Query RPC for transaction receipt
  → Check confirmation count
  → Update status when threshold met
```

### Event-Driven

WebSocket listeners monitor Transfer events in real-time:

```
On Transfer event:
  → Match to pending invoice
  → Verify amount and recipient
  → Update settlement status
```

## Settlement Events

When a settlement status changes, webhook events are fired:

| Event                  | Trigger                        |
| ---------------------- | ------------------------------ |
| `settlement.confirmed` | On-chain confirmation received |
| `settlement.failed`    | Settlement verification failed |

## Configuration

Settlement detection is automatic for all invoices. Configure timing via environment:

| Variable                   | Default   | Description                   |
| -------------------------- | --------- | ----------------------------- |
| `SETTLEMENT_POLL_INTERVAL` | 15000ms   | How often to check blockchain |
| `SETTLEMENT_TIMEOUT`       | 3600000ms | Max wait time (1 hour)        |
| `SETTLEMENT_CONFIRMATIONS` | 12        | Required block confirmations  |

## Supported Networks

| Network  | Chain ID | Token      |
| -------- | -------- | ---------- |
| Base     | 8453     | USDC       |
| Polygon  | 137      | USDC       |
| Arbitrum | 42161    | USDC       |
| Solana   | —        | USDC (SPL) |