Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

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

GET https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts
Authorization: Basic base64(client_id:client_secret)

All optional. Combine the ones you need.

ParamTypeDefaultDescription
pageint (≥ 1)1Pagination page
per_pageint (1–100)20Items per page
statusenum-pending, notfound, account_suspended, other, expired
provider_alert_idstring-Alert ID in the provider’s system (Ethoca/Verifi). Unique within each provider; usually returns 0 or 1 item
date_fromYYYY-MM-DD-Filters by received_at >= date_from (00:00:00 UTC)
date_toYYYY-MM-DD-Filters by received_at <= date_to (23:59:59 UTC)
card_binstring (6-8 digits)-Card BIN
card_last4string (4 digits)-Card last digits
merchant_idstring (UUID)-Only this merchant’s alerts
merchant_refstring (up to 100)-Only the alerts of the merchant with this reference from your system (see Create or update merchant). Without a merchant with the reference, the list comes back empty. The comparison ignores case and accents
merchant_enrollment_idstring (UUID)-Only the alerts that matched this enrollment (see Enrollments)
updated_sinceISO 8601 date and time with time zone-Only alerts changed from that moment on (e.g. 2026-11-06T12:00:00Z). Changes the order (see below)

With merchant_id and merchant_ref together, both must point to the same merchant; otherwise the list comes back empty.

With updated_since, the list brings only the alerts that changed from that moment on (a new alert or a status change), oldest first (updated_at, then id). To follow them without missing any:

  1. Keep the highest updated_at you received.
  2. On the next query, send that value minus 2 minutes as updated_since.
  3. Skip the (id, updated_at) pair you already processed.
  4. Read the pages up to total_pages.

The 2-minute margin covers a change saved out of order or during your read.


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:

Terminal window
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.


Terminal window
curl -G "https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts" \
--data-urlencode "status=pending" \
--data-urlencode "per_page=50" \
-H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
Terminal window
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="
Terminal window
curl -G "https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts" \
--data-urlencode "merchant_ref=PB-1001" \
-H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
Terminal window
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="

{
"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",
"merchant_ref": "PB-1001",
"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
}
}
{
"data": [],
"meta": { "page": 1, "per_page": 20, "total": 0, "total_pages": 0 }
}

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

Section titled “Invalid validation (e.g. non-numeric card_bin)”
{
"error": {
"code": "VALIDATION_ERROR",
"message": "card_bin must be 6-8 digits"
}
}

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.

Send one of the two:

FieldTypeDescription
alert_idstringAlert ID at the provider, the same one you receive in the legacy webhook format. Rapid’s UUID is also accepted
authorization_codestringTransaction 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.

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

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.

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

SituationResponse
Neither alert_id nor authorization_code400 {"error": "Informe alert_id ou authorization_code."}
None of your alerts matches404 {"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.


  • provider comes as a slug string ("ethoca_alerts" or "verifi_rdr"), the same as in the outbound webhook payload (v2 format).
  • merchant_ref is the merchant’s reference in your system (null when the alert has no merchant or the merchant has no reference). It also comes when you get an alert by id.
  • 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: by received_at descending (most recent first), with id breaking ties between alerts received at the same moment. With updated_since, by updated_at ascending, then id. There is no custom sort parameter.
  • Unknown parameters are still ignored on this route, but they will start being rejected with 422: send only the parameters in the table (see API changelog).
  • Auth, rate limit, error codes: see Authentication and Response codes.