Consultar alertas

Lista las alertas de contracargo de tu empresa, con filtros opcionales y paginación.

Endpoint

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

Autenticación

Authorization: Basic base64(client_id:client_secret)

---

Query params

Todos opcionales. Combina los que necesites.

Param	Tipo	Default	Descripción
page	int (≥ 1)	1	Página de la paginación
per_page	int (1–100)	20	Elementos por página
status	enum	-	pending, notfound, account_suspended, other, expired
provider_alert_id	string	-	ID de la alerta en el sistema del proveedor (Ethoca/Verifi). Único dentro de cada proveedor; normalmente devuelve 0 o 1 elemento
date_from	YYYY-MM-DD	-	Filtra por received_at >= date_from (00:00:00 UTC)
date_to	YYYY-MM-DD	-	Filtra por received_at <= date_to (23:59:59 UTC)
card_bin	string (6-8 dígitos)	-	BIN de la tarjeta
card_last4	string (4 dígitos)	-	Últimos dígitos de la tarjeta

---

Buscar por tu propio ID (el del proveedor)

Las alertas tienen dos IDs:

• id: UUID que Rapid genera cuando recibe la alerta. Es lo que necesitas para actualizar el estado (PATCH /chargeback-alert/alerts/:id/status).
• provider_alert_id: ID que generó Ethoca o Verifi. Es lo que probablemente ya tienes guardado en tus sistemas, del payload original del proveedor.

Si solo tienes el provider_alert_id y necesitas encontrar nuestro id (o los datos de la alerta), usa este endpoint con el filtro:

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

El provider_alert_id es único dentro de cada proveedor, así que la respuesta normalmente tendrá 1 elemento en data. Para una clave estable y globalmente única, usa el id (UUID) de la respuesta.

---

Ejemplos

Listar las últimas alertas pendientes

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

Alertas de los últimos 7 días

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

Buscar por tarjeta (BIN + últimos dígitos)

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

---

Respuesta

Éxito

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

Sin resultados

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

Validación inválida (ej.: card_bin no numérico)

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

---

Clientes del sistema anterior

Quien ya integraba con el sistema anterior puede seguir consultando una alerta por el endpoint antiguo, mantenido como alias:

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

Ten en cuenta que este alias no tiene el prefijo /api/v1. Acepta Basic Auth o los headers clientid/clientkey.

Cuerpo de la solicitud

Envía uno de los dos:

Campo	Tipo	Descripción
alert_id	string	ID de la alerta en el proveedor, el mismo que recibes en el formato legacy del webhook. El UUID de Rapid también se acepta
authorization_code	string	Código de autorización de la transacción

Si vienen los dos, alert_id tiene prioridad. Cuando más de una alerta coincide (por ejemplo, dos alertas con el mismo código de autorización), se devuelve la más reciente.

Ejemplo

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

Respuesta

200 con success y data, donde data es el mismo cuerpo del webhook en formato legacy (ver Formato legacy):

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

La respuesta viene con Cache-Control: no-store, como en el sistema anterior.

Errores de este alias

Para mantener la paridad con el sistema anterior, los errores de este endpoint usan el envelope antiguo ({"error": "texto"}), y no el envelope nuevo con code:

Situación	Respuesta
Ni alert_id ni authorization_code	400 {"error": "Informe alert_id ou authorization_code."}
Ninguna alerta tuya coincide	404 {"error": "Alerta não encontrado."}

Los mensajes están en portugués, tal como los devolvía el sistema anterior. En integraciones nuevas, prefiere GET /api/v1/chargeback-alert/alerts/:id, que usa el envelope de error estándar de la API.

---

Notas

• provider viene como string slug ("ethoca_alerts" o "verifi_rdr"), igual que en el payload del webhook saliente (formato v2).
• Los campos de la respuesta son exactamente los del ejemplo de arriba, más installment_number e installment_count (cuotas, los mismos del webhook) y provider_id, un identificador interno mantenido por compatibilidad: usa provider.
• Las fechas de “solo fecha” (transaction_date) llegan como "2026-04-01T00:00:00.000Z".
• Orden: siempre por received_at descendente (la más reciente primero). No hay parámetro de orden personalizado.
• Auth, rate limit, códigos de error: ver Autenticación y Códigos de respuesta.