List alerts

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)
date_to	YYYY-MM-DD	-	Filters by received_at <= date_to (23:59:59)
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:

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

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

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)

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

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

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

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

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

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):

{
  "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, 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 and Response codes.