> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bleepay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```shell theme={null}
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

```json theme={null}
[
  {
    "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          |