Como recuperar vendas recusadas no cartão

1. Diagnostique: quanto e por quê

curl -G "$HEROPAY_API_URL/reports/purchase/refused/reasons_count" \
  -H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  -d "start_date=2026-08-01" -d "end_date=2026-08-31"

A resposta agrupa as recusas do período por motivo; GET /reports/purchase/refused/sales, com os mesmos filtros, traz as vendas recusadas. Rode os dois uma vez no sandbox e confira o formato da resposta antes de automatizar a leitura; a lista completa está na documentação de relatórios de compras.

Leia o resultado em dois grupos. Recuperáveis: limite insuficiente, suspeita de fraude do emissor, dados digitados errado. Irrecuperáveis no mesmo cartão: cartão cancelado, bloqueado, vencido. O primeiro grupo pede retentativa e parcelamento; o segundo pede outro cartão ou Pix. Retentar cartão cancelado só queima tentativa.

A conta que justifica o trabalho, ilustrativa: 40 recusas por mês num produto de R$ 197 são R$ 7.880 parados. Recuperar um quarto delas devolve R$ 1.970 por mês, R$ 23.640 por ano, sem um centavo a mais de tráfego.

2. Deixe o checkout fazer a primeira recuperação

Antes de qualquer mensagem, o checkout hospedado já trabalha na hora da recusa:

• Retentativa pós-recusa no próprio checkout, sem o comprador recomeçar.
• Parcelamento Inteligente na recusa por limite: cobra a parcela do mês em vez de reservar o limite total, com até 3 retentativas por parcela.
• 2 cartões (50/50, parcelamento independente) em ofertas acima de R$ 100.
• Pix e boleto na mesma tela, quando o link aceita. Crie os links com "payment_methods": ["credit_card", "pix"] no mínimo: o Pix é a saída mais barata para quem teve o cartão negado (R$ 0 por transação).

É por isso que a aprovação no cartão fica em 93%+. O que sobra depois disso é o que a régua recupera.

3. Escute a recusa por webhook

curl -X POST "$HEROPAY_API_URL/webhook" \
  -H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "trigger": "payment_credit_cart_refused",
      "webhook_url": "https://seuapp.com/webhooks/heropay",
      "request_method": "post"
    }
  }'

Recorte dos campos que a régua usa (valores ilustrativos, campos reais do template; o payload completo está na documentação de webhooks):

{
  "buyer": { "name": "Ana Souza", "email": "ana@exemplo.com", "phone_raw": "11988887777" },
  "payment": { "id": "8812501", "method": "credit_card" },
  "offer": { "title": "Curso de Excel" },
  "cart": { "src": "ads-setembro" },
  "payment_methods": {
    "credit_card": { "refused_message": "Saldo insuficiente" }
  }
}

Valide X-HeroPay-Signature, deduplique por payment.id + gatilho e agende a régua. O texto de refused_message vem da operadora e varia: classifique por palavras-chave (limite, saldo, vencido, cancelado), deixe uma categoria "outros" como padrão e nunca faça a régua depender de uma frase exata.

4. Monte a régua

O webhook não traz a URL do checkout; guarde data.offer.url junto do src quando criar o link e reenvie a mesma URL. Uma régua enxuta, como ponto de partida para testar:

Personalize pelo motivo: limite pede "parcele" ou "divida em 2 cartões"; cartão cancelado pede "use outro cartão ou o Pix". Mensagem genérica de "pagamento recusado" recupera menos. Use o contato só para concluir a compra que a pessoa iniciou e ofereça saída da lista, em linha com a LGPD.

5. Recupere também quem abandonou

Quem preencheu os dados e saiu sem tentar pagar não gera recusa. Puxe os abandonos do dia:

curl -G "$HEROPAY_API_URL/reports/tracking/abandoned_carts" \
  -H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  -d "start_date=2026-09-23" -d "end_date=2026-09-23"

Um carrinho conta como abandonado quando o comprador acessa o checkout, preenche e-mail ou telefone e não paga. Pelo painel, a automação de carrinho abandonado dispara em 15 minutos. Para a lista de recusadas com contato do comprador, GET /transactions/by_status?status=refused traz buyer, cart.src e transaction.payment_method de cada tentativa.