Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.garu.com.br/llms.txt

Use this file to discover all available pages before exploring further.

A partir da v0.8.0, toda falha de pagamento traz um código canônico estável (failureCode), uma mensagem em português (failureReason) e o código bruto do gateway (gatewayFailureCode). Você roteia em cima do enum normalizado e ainda tem o código original para auditoria / abertura de chamado com Celcoin.

​
Onde aparece

WebhookCampo
transaction.payment.faileddata.failureCode, data.failureReason, data.gatewayFailureCode
scheduled_charge.cycle_faileddata.failureCode, data.failureReason, data.gatewayFailureCode
GET /api/scheduled-charges/:id/attemptsem cada item: failureCode, failureReason, gatewayFailureCode

​
Valores

failureCodeSignificadoAção típica
insufficient_fundsSaldo insuficienteAguardar; tentar novamente em horizonte de dias
card_declinedRecusa genérica do emissorAvisar cliente; sugerir outro cartão
card_expiredCartão vencidoColetar novo cartão (a Garu já avisa via payment_method.expiring_soon)
card_canceledCartão cancelado pelo emissorColetar novo cartão; permanente
processing_errorErro no processamento (gateway / rede / token)Retry automático cuidará
issuer_unavailableEmissor indisponívelRetry automático
fraud_suspectedSuspeita de fraudeNão tentar de novo; pedir contato com emissor
invalid_cvvCVV inválidoPedir cliente para reentrar dados
do_not_honor_repeated”Do not honor” persistenteSugerir outro cartão; emissor recusando
unknownNão mapeado pela GaruInspecionar gatewayFailureCode

​
Mapeamento ABECS → Garu

A Garu normaliza os códigos ABECS retornados pelo Celcoin. O código original fica em gatewayFailureCode:
ABECSfailureCode
00(sucesso, não há failureCode)
51, 61, 65insufficient_funds
54card_expired
41, 43, 93fraud_suspected
82, N7invalid_cvv
91, 92, 96issuer_unavailable
05 (repetido)do_not_honor_repeated
outros 0x / 1xcard_declined
Códigos não-ABECS (mensagem livre do Celcoin) caem em keyword matching: a Garu varre a reasonDenied por palavras-chave em PT/EN (“vencido”, “expired”, “insufficient”, etc.) e mapeia para o melhor enum. Se nada bate: unknown.

​
Exemplo

{
  "event": "transaction.payment.failed",
  "data": {
    "id": 999,
    "value": 49.9,
    "failureCode": "insufficient_funds",
    "failureReason": "Saldo insuficiente",
    "gatewayFailureCode": "51"
  }
}

​
Boas práticas de roteamento

card_expired, card_canceled, fraud_suspected → coletar dados novos. Não vale a pena automatizar retry. insufficient_funds, issuer_unavailable, processing_error → a Garu já tenta automaticamente; relaxe.
gatewayFailureCode muda quando trocamos de gateway por baixo. failureCode é estável. Use o enum para automação; logue o gateway code para forensics.
Para scheduled_charge.cycle_failed, a Garu já tentou em +6h, +24h, +48h antes de emitir o evento. Não tente cobrar de novo programaticamente — peça novo cartão ou aguarde o cliente clicar no e-mail de fallback.