Query Refund Sessions

List refund sessions for a business.

GET /api/v1/widgets/refund-sessions

Returns a paginated list of refund sessions belonging to the authenticated business. You can filter by widget, deposit session, and payment status.

Parameters

Query

Name	Type	Required	Description
businessId	string	Conditionally	The business ID. Required unless widgetId is provided
widgetId	string	Conditionally	Filter by widget ID. Required unless businessId is provided
depositSessionId	string	No	Filter by parent deposit session ID
paymentStatus	string	No	Filter by payment status: CREATED, PENDING, CONFIRMED, EXPIRED, FAILED, CANCELLED
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

Filter operators

Apply operators to any filterable field using bracket notation: field[operator]=value.

Operator	Description	Example
eq	Equal to	?paymentStatus[eq]=CONFIRMED
ne	Not equal to	?paymentStatus[ne]=EXPIRED
in	In array	?paymentStatus[in]=CONFIRMED&paymentStatus[in]=PENDING

A plain value without bracket notation is treated as eq: ?paymentStatus=CONFIRMED.

Request example

curl --request GET 'https://payments.bleepay.com/api/v1/widgets/refund-sessions?businessId=biz_abc123&paymentStatus=CONFIRMED&limit=20' \
  --header 'Authorization: Bearer <business_token>'

Response

Response schema

Field	Type	Description
id	string	Unique refund session identifier
businessId	string	The business ID
widgetId	string	The widget ID
depositSessionId	string	The parent deposit session ID
paymentStatus	string	Status: CREATED, PENDING, CONFIRMED, EXPIRED, FAILED, CANCELLED
amount	string	Refund amount
amountRaw	string	Raw amount in lowest denominator
currency	string	Currency symbol
network	string	Blockchain network
currencyAddress	string	Currency contract address
dstAddress	string	Refund destination address
value	string	Estimated USD value
valueRaw	string	Raw USD value in lowest denominator
confirmedTxid	string or null	Confirmed blockchain transaction hash
confirmedPayerAddress	string or null	Confirmed payer wallet address
expiresAt	string	ISO 8601 expiry timestamp
confirmedAt	string or null	ISO 8601 confirmation timestamp
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

Example response

[
  {
    "id": "ref_a1b2c3d4e5f6",
    "businessId": "biz_abc123",
    "widgetId": "wdgt_abc",
    "depositSessionId": "dep_a1b2c3d4e5f6",
    "paymentStatus": "CONFIRMED",
    "amount": "100",
    "amountRaw": "100000000",
    "currency": "USDC",
    "network": "polygon",
    "currencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
    "dstAddress": "0xPayerWalletAddress",
    "value": "100.00",
    "valueRaw": "10000",
    "confirmedTxid": "0xabc123def456...",
    "confirmedPayerAddress": "0xPayerWallet123...",
    "expiresAt": "2026-06-09T12:30:00.000Z",
    "confirmedAt": "2026-06-09T12:05:00.000Z",
    "createdAt": "2026-06-09T12:00: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