Documentation Index
Fetch the complete documentation index at: https://docs.stablegenius.co/llms.txt
Use this file to discover all available pages before exploring further.
Webhook Events
This is the complete reference for all webhook events fired by Stable Genius.
Event Envelope
Every webhook event shares this envelope structure:
{
"id": "evt_*",
"object": "event",
"type": "event.type",
"api_version": "2026-04-01",
"created_at": "ISO 8601 timestamp",
"data": { /* event-specific payload */ }
}
Payment Intent Events
payment_intent.confirmed
Fired when USDC is received and confirmed on-chain for a payment intent.
{
"id": "evt_pi_conf_001",
"object": "event",
"type": "payment_intent.confirmed",
"api_version": "2026-04-01",
"created_at": "2026-04-01T20:00:12Z",
"data": {
"id": "pi_xyz789",
"object": "payment_intent",
"status": "confirmed",
"amount": 4.50,
"currency": "usd",
"net_amount": 4.455,
"fee": 0.045,
"fee_rate": 0.01,
"merchant_id": "mer_abc123",
"payment_address": "0x1a2b...cdef",
"tx_hash": "0xabc1...f456",
"chain": "base",
"token": "USDC",
"sender_address": "0x9876...5432",
"block_number": 12345678,
"confirmed_at": "2026-04-01T20:00:12Z",
"metadata": {
"order_id": "order_456",
"terminal_id": "pos_01"
}
}
}
payment_intent.expired
Fired when a payment intent expires without receiving payment.
{
"id": "evt_pi_exp_001",
"object": "event",
"type": "payment_intent.expired",
"api_version": "2026-04-01",
"created_at": "2026-04-01T20:05:00Z",
"data": {
"id": "pi_xyz789",
"object": "payment_intent",
"status": "expired",
"amount": 4.50,
"currency": "usd",
"merchant_id": "mer_abc123",
"expired_at": "2026-04-01T20:05:00Z",
"metadata": {
"order_id": "order_456"
}
}
}
payment_intent.cancelled
Fired when an integrator cancels a payment intent.
{
"id": "evt_pi_can_001",
"object": "event",
"type": "payment_intent.cancelled",
"api_version": "2026-04-01",
"created_at": "2026-04-01T20:02:30Z",
"data": {
"id": "pi_xyz789",
"object": "payment_intent",
"status": "cancelled",
"amount": 4.50,
"currency": "usd",
"merchant_id": "mer_abc123",
"cancelled_at": "2026-04-01T20:02:30Z",
"metadata": {
"order_id": "order_456"
}
}
}
Transaction Events
transaction.created
Fired when any USDC transfer is detected at a merchant’s payment address, even if not tied to an active payment intent. Use this as a catch-all for incoming payments.
{
"id": "evt_txn_crt_001",
"object": "event",
"type": "transaction.created",
"api_version": "2026-04-01",
"created_at": "2026-04-01T20:00:12Z",
"data": {
"id": "txn_def456",
"object": "transaction",
"payment_intent_id": "pi_xyz789",
"merchant_id": "mer_abc123",
"status": "confirmed",
"amount": 4.50,
"currency": "usd",
"net_amount": 4.455,
"fee": 0.045,
"chain": "base",
"token": "USDC",
"tx_hash": "0xabc1...f456",
"sender_address": "0x9876...5432",
"confirmed_at": "2026-04-01T20:00:12Z"
}
}
payment_intent_id may be null if the transaction wasn’t associated with a specific payment intent (e.g., a direct transfer to the merchant’s address).
Settlement Events
settlement.completed
Fired when a merchant’s funds are successfully sent to their bank account.
{
"id": "evt_stl_cmp_001",
"object": "event",
"type": "settlement.completed",
"api_version": "2026-04-01",
"created_at": "2026-04-01T08:00:00Z",
"data": {
"id": "stl_ghi789",
"object": "settlement",
"merchant_id": "mer_abc123",
"amount": 142.55,
"currency": "usd",
"status": "completed",
"bank_name": "Wells Fargo",
"bank_last_4": "0468",
"estimated_arrival": "2026-04-03",
"initiated_at": "2026-04-01T08:00:00Z"
}
}
settlement.failed
Fired when an ACH transfer to a merchant’s bank fails (e.g., invalid account, NSF return).
{
"id": "evt_stl_fld_001",
"object": "event",
"type": "settlement.failed",
"api_version": "2026-04-01",
"created_at": "2026-04-03T14:30:00Z",
"data": {
"id": "stl_ghi789",
"object": "settlement",
"merchant_id": "mer_abc123",
"amount": 142.55,
"currency": "usd",
"status": "failed",
"failure_reason": "account_closed",
"failure_message": "The bank account has been closed. Please update bank details.",
"initiated_at": "2026-04-01T08:00:00Z",
"failed_at": "2026-04-03T14:30:00Z"
}
}
