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"
  }
}

Overview

Payment Intents

Transactions

Merchants

Webhooks

Webhook Events

Webhook Events

Event Envelope

Payment Intent Events

payment_intent.confirmed

payment_intent.expired

payment_intent.cancelled

Transaction Events

transaction.created

Settlement Events

settlement.completed

settlement.failed

​Webhook Events

​Event Envelope

​Payment Intent Events

​payment_intent.confirmed

​payment_intent.expired

​payment_intent.cancelled

​Transaction Events

​transaction.created

​Settlement Events

​settlement.completed

​settlement.failed

Webhook Events

Event Envelope

Payment Intent Events

payment_intent.confirmed

payment_intent.expired

payment_intent.cancelled

Transaction Events

transaction.created

Settlement Events

settlement.completed

settlement.failed