Chargeback

Chargeback é o emissor do cartão devolvendo o dinheiro ao titular depois de uma reclamação. No fluxo da Zhex hoje, ele se comporta como reembolso compulsório: o valor sai do seu saldo, o cliente recebe de volta, e não há janela de resposta com evidência — diferente do modelo Stripe/Adyen, onde você submete documentação para tentar reverter.

A regra prática: se chargeback chegou, o dinheiro já foi. Tudo que você pode fazer é registrar contabilmente, comunicar com o cliente, e reduzir a recorrência via prevenção.

Como você fica sabendo

A Zhex emite o webhook charge.dispute.created assim que o chargeback é recebido do emissor. Esse é o único event do recurso hoje — não há won/lost/under_review no lifecycle público.

import Zhex from '@zhexio/node';

app.post(
  '/webhooks/zhex',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const event = Zhex.webhooks.constructEvent(
      req.body,
      req.headers['zhex-signature'] as string,
      process.env.ZHEX_WEBHOOK_SECRET!,
    );

    if (event.type === 'charge.dispute.created') {
      const intent = event.data.object as { id: string; amount: number; customer: string | null };
      // 1. registrar perda contábil
      // 2. email para o cliente confirmando que recebeu o estorno
      // 3. opcionalmente, revogar acesso ao produto/conta
    }

    res.json({ received: true });
  },
);

O event.data.object é o PaymentIntent original — você usa o id para correlacionar com a venda no seu sistema, e amount para a baixa contábil.

O que fazer ao receber

1. Marcar a venda como estornada no seu BD. Para o cliente, o efeito é equivalente a um refund — o produto deve sair da conta dele se aplicável.
2. Email transacional confirmando o estorno. Reduz suporte e mostra que você está atento, mesmo perdendo a transação.
3. Revogar acesso se for produto digital / SaaS — chargeback frequentemente é abuso. Sem revogação, vira fraude amiga (cliente fica com produto e dinheiro).
4. Registrar contabilmente. Para fechamento mensal, o chargeback é um custo direto — taxa fixa do emissor + valor da transação.

Custos

Prevenção

Como não há resposta, o caminho é evitar:

• 3DS em ticket > R$ 200 ou customer novo. O 3DS faz liability shift — em transações autenticadas, o emissor não pode abrir chargeback por "não reconheço". Custo zero quando o emissor aceita frictionless.
• statement_descriptor claro. "ZHEX*MEUSITE_PREMIUM" > "ZHX BR PAYMNT 8392". 40% dos chargebacks de fraude começam por "não reconheço esta cobrança".
• Email pós-cobrança com nota fiscal/recibo, link de suporte e descrição clara do produto. Reduz "fraude amiga" — cliente que não lembra do que comprou.
• Cancelamento auto-servido em assinatura. Se o cliente não consegue cancelar pelo painel, ele cancela via cartão (= chargeback). Cancele com 1 clique, sempre.
• Refund proativo em queixas legítimas. Se o cliente reclamou e você sabe que tem razão, dê o refund antes que ele abra chargeback. Refund custa só o valor; chargeback custa valor + taxa + ratio.
• Bloqueio de IP/device repetente. Mesmo customer.document ou IP gerando múltiplos chargebacks → blocklist interna.

Métrica que importa

Chargeback ratio = chargebacks do mês ÷ transações aprovadas do mês.

Acompanhe em Dashboard → Transações → Chargebacks semanalmente.