# List alerts

> Lists your company's chargeback alerts, with optional filters and pagination.

Página: https://doc.rapidchargeback.com/en/callback/consultar-alertas/

Lists your company's chargeback alerts, with optional filters and pagination.

## Endpoint

```
GET https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts
```

## Authentication

```
Authorization: Basic base64(client_id:client_secret)
```

---

## Query params

All optional. Combine the ones you need.

| Param | Type | Default | Description |
|---|---|---|---|
| `page` | int (≥ 1) | `1` | Pagination page |
| `per_page` | int (1–100) | `20` | Items per page |
| `status` | enum | - | `pending`, `notfound`, `account_suspended`, `other`, `expired` |
| `provider_alert_id` | string | - | Alert ID in the provider's system (Ethoca/Verifi). Unique within each provider; usually returns 0 or 1 item |
| `date_from` | YYYY-MM-DD | - | Filters by `received_at >= date_from` (00:00:00 UTC) |
| `date_to` | YYYY-MM-DD | - | Filters by `received_at <= date_to` (23:59:59 UTC) |
| `card_bin` | string (6-8 digits) | - | Card BIN |
| `card_last4` | string (4 digits) | - | Card last digits |

---

## Search by your own ID (the provider's)

Alerts have two IDs:

- **`id`**: UUID that Rapid generates when it receives the alert. It is what you need to update the status (`PATCH /chargeback-alert/alerts/:id/status`).
- **`provider_alert_id`**: ID generated by Ethoca or Verifi. It is what you probably already have stored in your systems, from the provider's original payload.

If you only have the `provider_alert_id` and need to find our `id` (or the alert data), use this endpoint with the filter:

```bash
curl -G "https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts" \
  --data-urlencode "provider_alert_id=ALERT-ETHOCA-12345" \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
```

The `provider_alert_id` is unique within each provider, so the response will usually have 1 item in `data`. For a stable, globally unique key, use the `id` (UUID) in the response.

---

## Examples

### List the latest pending alerts

```bash
curl -G "https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts" \
  --data-urlencode "status=pending" \
  --data-urlencode "per_page=50" \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
```

### Alerts from the last 7 days

```bash
curl -G "https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts" \
  --data-urlencode "date_from=2026-04-16" \
  --data-urlencode "date_to=2026-04-23" \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
```

### Search by card (BIN + last digits)

```bash
curl -G "https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts" \
  --data-urlencode "card_bin=424242" \
  --data-urlencode "card_last4=4242" \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
```

---

## Response

### Success

```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000099",
      "company_id": "00000000-0000-0000-0000-0000000000c1",
      "merchant_id": "00000000-0000-0000-0000-000000000001",
      "merchant_enrollment_id": "00000000-0000-0000-0000-0000000000aa",
      "provider": "ethoca_alerts",
      "provider_alert_id": "ALERT-ETHOCA-12345",
      "amount": "150.00",
      "currency": "USD",
      "card_last4": "4242",
      "card_bin": "424242",
      "transaction_date": "2026-04-01T00:00:00.000Z",
      "descriptor": "LOJA EXEMPLO",
      "arn": null,
      "caid": null,
      "auth_code": "AUTH999",
      "alert_type": "fraud",
      "reason_code": "10.4",
      "issuer": "BANK XYZ",
      "status": "pending",
      "received_at": "2026-04-23T10:15:00.000Z",
      "expires_at": "2026-04-24T10:15:00.000Z",
      "created_at": "2026-04-23T10:15:00.000Z",
      "updated_at": "2026-04-23T10:15:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 42,
    "total_pages": 3
  }
}
```

### No results

```json
{
  "data": [],
  "meta": { "page": 1, "per_page": 20, "total": 0, "total_pages": 0 }
}
```

### Invalid validation (e.g. non-numeric `card_bin`)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "card_bin must be 6-8 digits"
  }
}
```

---

## Customers from the previous system

Those who already integrated with the previous system can still look up an alert through the old endpoint, kept as an alias:

```
POST https://api.rapidchargeback.com/chargeback-alert/get
```

Note that this alias does **not** have the `/api/v1` prefix. It accepts Basic Auth or the `clientid`/`clientkey` headers.

### Request body

Send **one** of the two:

| Field | Type | Description |
|---|---|---|
| `alert_id` | string | **Alert ID at the provider**, the same one you receive in the `legacy` webhook format. Rapid's UUID is also accepted |
| `authorization_code` | string | Transaction authorization code |

If both are sent, `alert_id` takes priority. When more than one alert matches (for example, two alerts with the same authorization code), the most recent one is returned.

### Example

```bash
curl -X POST https://api.rapidchargeback.com/chargeback-alert/get \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{ "alert_id": "ETH-99887766" }'
```

### Response

`200` with `success` and `data`, where `data` is the **same body as the webhook in `legacy` format** (see [Legacy format](https://doc.rapidchargeback.com/en/canais/webhook/payload/#legacy-format)):

```json
{
  "success": true,
  "data": {
    "alert_id": "ETH-99887766",
    "merchant": "Minha Loja",
    "provider": "ethoca",
    "descriptor": "LOJA EXEMPLO",
    "transaction_date": "2026-04-01T00:00:00.000Z",
    "currency": "USD",
    "amount": 150,
    "card_number": "424242******4242",
    "created_at": "2026-04-14T12:00:00.000Z"
  }
}
```

The response comes with `Cache-Control: no-store`, as in the previous system.

### Errors of this alias

To keep parity with the previous system, the errors of this endpoint use the **old** envelope (`{"error": "text"}`), not the new envelope with `code`:

| Situation | Response |
|---|---|
| Neither `alert_id` nor `authorization_code` | `400` `{"error": "Informe alert_id ou authorization_code."}` |
| None of your alerts matches | `404` `{"error": "Alerta não encontrado."}` |

The messages are in Portuguese, exactly as the previous system returned them. In new integrations, prefer [`GET /api/v1/chargeback-alert/alerts/:id`](#endpoint), which uses the API's standard error envelope.

---

## Notes

- **`provider`** comes as a slug string (`"ethoca_alerts"` or `"verifi_rdr"`), the same as in the outbound webhook payload (`v2` format).
- The response fields are exactly those in the example above, plus `installment_number` and `installment_count` (installments, the same as in the webhook) and `provider_id`, an internal identifier kept for compatibility: use `provider`.
- Date-only values (`transaction_date`) arrive as `"2026-04-01T00:00:00.000Z"`.
- **Sorting:** always by `received_at` descending (most recent first). There is no custom sort parameter.
- **Auth, rate limit, error codes:** see [Authentication](https://doc.rapidchargeback.com/en/referencia/autenticacao/) and [Response codes](https://doc.rapidchargeback.com/en/referencia/codigos-de-resposta/).