Consultar alertas

Lista os alertas de chargeback da sua empresa, com filtros opcionais e paginação.

Endpoint

GEThttps://api.rapidchargeback.com/api/v1/chargeback-alert/alerts

Autenticação

Authorization: Basic base64(client_id:client_secret)

---

Query params

Todos opcionais. Combine os que precisar.

Param	Tipo	Default	Descrição
page	int (≥ 1)	1	Página da paginação
per_page	int (1–100)	20	Itens por página
status	enum	-	pending, notfound, account_suspended, other, expired
provider_alert_id	string	-	ID do alerta no sistema do provedor (Ethoca/Verifi). Único dentro de cada provedor; normalmente devolve 0 ou 1 item
date_from	YYYY-MM-DD	-	Filtra por received_at >= date_from (00:00:00)
date_to	YYYY-MM-DD	-	Filtra por received_at <= date_to (23:59:59)
card_bin	string (6-8 dígitos)	-	BIN do cartão
card_last4	string (4 dígitos)	-	Final do cartão

---

Buscar pelo seu próprio ID (do provedor)

Os alertas têm dois IDs:

• id: UUID que a Rapid gera quando recebe o alerta. É o que você precisa para atualizar status (PATCH /chargeback-alert/alerts/:id/status).
• provider_alert_id: ID que o Ethoca ou Verifi gerou. É o que você provavelmente já tem armazenado nos seus sistemas, vindo do payload original do provedor.

Se você só tem o provider_alert_id e precisa achar o nosso id (ou os dados do alerta), use este endpoint com o filter:

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

O provider_alert_id é único dentro de cada provedor, então a resposta normalmente terá 1 item em data. Para uma chave estável e globalmente única, use o id (UUID) que vem na resposta.

---

Exemplos

Listar últimos alertas pendentes

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 dos últimos 7 dias

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 cartão (BIN + final)

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

---

Resposta

Sucesso

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

Sem resultados

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

Validação inválida (ex: card_bin não-numérico)

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

---

Clientes do sistema anterior

Quem já integrava com o sistema anterior continua podendo consultar um alerta pelo endpoint antigo, mantido como alias:

POSThttps://api.rapidchargeback.com/chargeback-alert/get

Note que este alias não tem o prefixo /api/v1. Ele aceita Basic Auth ou os headers clientid/clientkey.

Corpo da requisição

Informe um dos dois:

Campo	Tipo	Descrição
alert_id	string	ID do alerta no provedor, o mesmo que você recebe no webhook em formato legacy. O UUID da Rapid também é aceito
authorization_code	string	Código de autorização da transação

Se os dois vierem, alert_id tem prioridade. Quando mais de um alerta casa (por exemplo, dois alertas com o mesmo código de autorização), volta o mais recente.

Exemplo

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

Resposta

200 com success e data, onde data é o mesmo corpo do webhook em 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"
  }
}

A resposta vem com Cache-Control: no-store, como no sistema anterior.

Erros deste alias

Para manter a paridade com o sistema anterior, os erros deste endpoint usam o envelope antigo ({"error": "texto"}), e não o envelope novo com code:

Situação	Resposta
Nem alert_id nem authorization_code	400 {"error": "Informe alert_id ou authorization_code."}
Nenhum alerta seu corresponde	404 {"error": "Alerta não encontrado."}

Em integrações novas, prefira GET /api/v1/chargeback-alert/alerts/:id, que usa o envelope de erro padrão da API.

---

Notas

• provider vem como string slug ("ethoca_alerts" ou "verifi_rdr"), igual ao payload do webhook outbound (formato v2).
• Os campos da resposta são exatamente os do exemplo acima, mais installment_number e installment_count (parcelamento, os mesmos do webhook) e provider_id, um identificador interno mantido por compatibilidade: use provider.
• Datas do tipo “só data” (transaction_date) chegam como "2026-04-01T00:00:00.000Z".
• Ordenação: sempre por received_at decrescente (mais recente primeiro). Não há parâmetro de ordenação custom.
• Auth, rate limit, códigos de erro: ver Autenticação e Códigos de resposta.