Skip to main content
GET
/
api
/
scheduled-charges
/
{id}
/
attempts
Listar tentativas de cobrança
curl --request GET \
  --url https://garu.com.br/api/scheduled-charges/{id}/attempts \
  --header 'Authorization: Bearer <token>'
Disponível a partir da v0.8.2. Retorna uma linha por tentativa lógica de cobrança em todos os ciclos da série — ciclo 1 interativo, cada cobrança silenciosa, cada retry, cada mark-paid manual. Cada linha carrega o failureCode canônico para recusas, possibilitando auditar por que uma série recorrente caiu em atraso.

​
Quando usar

  • Debug de cliente reclamando “minha cobrança falhou e não sei por quê”
  • Dashboard interno mostrando histórico de tentativas
  • Auditoria de SLA: quantas tentativas a Garu fez antes de marcar como overdue

​
Query params

ParamTipoDefault
cycleNumberint(todos os ciclos)
pageint1
limitint (1..100)20

​
Resposta

{
  "data": [
    {
      "id": 1234,
      "cycleId": "scc_01HG...",
      "cycleNumber": 3,
      "attemptNumber": 4,
      "attemptedAt": "2026-05-04T19:00:00Z",
      "source": "card_retry",
      "paymentMethod": "card",
      "paymentMethodId": 99,
      "cardLast4": "4242",
      "cardBrand": "visa",
      "status": "declined",
      "failureCode": "insufficient_funds",
      "failureReason": "Saldo insuficiente",
      "gatewayFailureCode": "51",
      "gatewayChargeId": 887766,
      "transactionId": 5544
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 5, "totalPages": 1 }
}

​
Origem da tentativa (source)

ValorDescrição
cycle1_interactiveCliente pagou no link público do ciclo 1 (tokenização inicial)
silent_chargeCron de billing cobrou silenciosamente o cartão salvo (ciclo N≥2)
card_retryCron de retry chamou o endpoint nativo de retry do gateway
manual_mark_paidSeller marcou ciclo como pago manualmente
fallback_pix(reservado; ainda não emitido)

​
Status

ValorDescrição
pendingRequisição feita, aguardando webhook do gateway
succeededConvertido em transação paga
declinedNegado pelo emissor (ver failureCode)
canceledCancelado antes de completar
erroredErro técnico — distinto de declined (rede, 5xx, etc.)
O snapshot de cardLast4 / cardBrand é capturado no momento da tentativa e sobrevive à exclusão do PaymentMethod (LGPD removal). paymentMethodId pode ficar null se a row foi deletada, mas você ainda vê o final do cartão.

​
Exemplo

Auditoria de uma série em atraso: 
# Quantas vezes tentamos cobrar o ciclo 3?
curl https://garu.com.br/api/scheduled-charges/sch_abc/attempts?cycleNumber=3 \
  -H "Authorization: Bearer $GARU_API_KEY"

// Pegando todas as recusas com falha distinta
import { Garu } from '@garuhq/node';
const garu = new Garu({ apiKey: process.env.GARU_API_KEY! });

const { data } = await garu.scheduledCharges.listAttempts('sch_abc');
const declines = data.filter((a) => a.status === 'declined');
const codes = new Set(declines.map((a) => a.failureCode));
// → Set { 'insufficient_funds', 'issuer_unavailable' }

​
SDK

const result = await garu.scheduledCharges.listAttempts('sch_abc', {
  cycleNumber: 3,
  page: 1,
  limit: 50,
});

​
MCP

Ferramenta list_scheduled_charge_attempts — agentes podem inspecionar histórico de cobrança como parte de fluxos de suporte.