Query Widget Events

List widget events (state transitions) for a business.

GET /api/v1/widgets/events

Returns a paginated list of widget events that record every state transition in a deposit session’s lifecycle. Each event has a type indicating what changed, and a payload with the full event data.

Parameters

Query

Name	Type	Required	Description
businessId	string	Yes	The business ID
depositSessionId	string	No	Filter by deposit session ID
widgetId	string	No	Filter by widget ID
type	string	No	Filter by event type. See event types below
status	string	No	Filter by event status: PENDING, ENABLED, DISABLED, SUSPENDED
limit	integer	No	Number of items (default 20, max 100)
offset	integer	No	Pagination offset
since	integer	No	Unix timestamp (ms) — return items created after this time
until	integer	No	Unix timestamp (ms) — return items created before this time

Event types

Type	Description
deposit.created	A new deposit session was created
deposit.pending	A matching on-chain transaction was detected but not yet confirmed
deposit.confirmed	The deposit has been confirmed on-chain
deposit.expired	The deposit session expired before a matching transaction was found
deposit.failed	The deposit could not be processed
deposit.underpaid	The on-chain amount is less than the requested amount
deposit.overpaid	The on-chain amount is more than the requested amount
deposit.unmatched	An on-chain transaction was detected but could not be matched to any session

Request example

curl --request GET 'https://payments.bleepay.com/api/v1/widgets/events?businessId=biz_abc123&type=deposit.confirmed&since=1717200000000&limit=20' \
  --header 'Authorization: Bearer <business_token>'

Response

Response schema

Field	Type	Description
id	string	Unique event identifier
businessId	string	The business ID
depositSessionId	string	The deposit session ID
type	string	Event type (e.g. deposit.created)
payload	object	Full event data specific to the event type
status	string	Event status: PENDING, ENABLED, DISABLED, SUSPENDED
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

Example response

[
  {
    "id": "evt_abc123",
    "businessId": "biz_abc123",
    "depositSessionId": "dep_a1b2c3d4e5f6",
    "type": "deposit.confirmed",
    "payload": {
      "amount": "100",
      "currency": "USDC",
      "network": "polygon",
      "txid": "0x7a1b2c3d...",
      "srcAddress": "0xPayerWallet123..."
    },
    "status": "ENABLED",
    "createdAt": "2026-06-09T12:05:00.000Z",
    "updatedAt": "2026-06-09T12:05:00.000Z"
  }
]

Error responses

Status	Code	Description
401	unauthorized	Missing or invalid authentication
400	validation_failed	Invalid query parameters