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 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) |
