Contestação de chargeback Pagar.me: dashboard e integração via API

Como o Pagar.me opera chargeback

O Pagar.me (do grupo Stone) é o gateway/PSP mais usado por e-commerces de médio porte no Brasil, especialmente os que rodam em plataformas próprias ou Shopify. O fluxo de contestação tem dois canais:

• Dashboard: dashboard.pagar.me → Disputas. Interface para resposta manual.
• API: v5 da Pagar.me API (api.pagar.me/core/v5) com endpoints específicos de Disputes, ideal para EC com integração técnica.

A particularidade do Pagar.me é o foco em desenvolvedores — então a documentação técnica é boa, mas a UI do dashboard exige um pouco mais de familiaridade que Stone Conta ou Cielo Backoffice.

Prazo Pagar.me

O prazo Pagar.me varia significativamente por código:

• 7 dias para a maioria dos chargebacks de fraude.
• 15 dias para códigos de consumidor padrão (13.x / 4855).
• Até 30 dias em casos específicos onde Pagar.me solicita evidências adicionais via "Document Request".

Pagar.me notifica por e-mail e pelo dashboard, e também via webhook se você assinou o evento charge.dispute.opened.

Passo a passo no Dashboard

1. Acesse dashboard.pagar.me com seu login.
2. Vá em "Disputas" no menu lateral. A lista mostra status (Open, Lost, Won).
3. Clique no caso. Você vê: ID da dispute, charge_id, valor, reason code (em inglês), prazo, status atual.
4. Clique em "Submit evidence". Abre formulário com campos por categoria de evidência (em inglês, baseado nas categorias da Stripe-like API).
5. Anexe documentos. Pagar.me aceita PDFs até 20 MB cada. Categorias do formulário:
   • access_activity_log — log de acesso (produto digital).
   • customer_communication — chat/e-mail.
   • customer_signature — comprovante assinado.
   • receipt — recibo/NF.
   • shipping_documentation — AR/transportadora.
   • service_documentation — comprovante de serviço prestado.
   • uncategorized_file — qualquer outro PDF.
6. Texto justificativo: campo "uncategorized_text" aceita até 20.000 caracteres.
7. Submeta. Status muda para "Under Review".

Integração via API

Para automação, a Pagar.me oferece endpoints REST completos. Exemplo:

• GET /core/v5/charges/{charge_id}/disputes — lista disputes.
• POST /core/v5/disputes/{id}/evidences — anexa documento (multipart/form-data).
• POST /core/v5/disputes/{id}/submit — submete a defesa.
• Webhook charge.dispute.opened, charge.dispute.won, charge.dispute.lost.

Para EC com mais de 50 chargebacks/mês, a integração paga o esforço inicial (~3–5 dias de dev) em 1–2 meses por reduzir tempo médio de resposta e padronizar o pacote.

Particularidades Pagar.me

• Categorias estruturadas (não é PDF único). Cada tipo de evidência tem seu campo. Use isso a favor — analista da bandeira vê o pacote organizado por categoria.
• Limite generoso de 20 MB por anexo é o maior do mercado brasileiro.
• Texto em inglês nos campos do formulário (legado da API estilo Stripe). Não interfere no resultado mas confunde inicialmente.
• Reason codes em inglês também (ex.: "fraudulent" para Visa 10.4). Mapeamento na documentação do Pagar.me.
• Para customers com 3DS, o Pagar.me automaticamente apresenta o log junto à dispute — você não precisa anexar.

Erros comuns na contestação Pagar.me

• Submeter tudo como uncategorized_file. Perde o ganho de organização do formulário estruturado.
• Ignorar webhook e descobrir o chargeback só pelo e-mail. O webhook permite resposta em minutos.
• Não fazer chamada explícita ao /submit depois de anexar — a evidência fica em rascunho e não é avaliada.
• Pular o campo uncategorized_text. Use-o como sua carta de defesa.

Outros adquirentes

• Contestação chargeback Cielo — para EC com Cielo direto.
• Contestação chargeback Stone — empresa-mãe do Pagar.me.
• Contestação chargeback Mercado Pago — fluxo MP.

Perguntas frequentes

O que muda entre contestar no Pagar.me e na Stone?

Pagar.me e Stone são da mesma empresa, mas têm fluxos de contestação distintos. Pagar.me usa categorias estruturadas estilo Stripe API (com 7 tipos de evidência), aceita anexos de até 20 MB e tem API completa. Stone usa wizard de 3 etapas no Stone Conta, anexos até 15 MB e API em beta-fechado. Para times técnicos, Pagar.me é mais flexível.

Pagar.me tem webhook para chargeback?

Sim. Os eventos relevantes são charge.dispute.opened (chargeback notificado), charge.dispute.under_review (após submeter defesa), charge.dispute.won e charge.dispute.lost. Configure no Dashboard ou via API. Permite resposta automática em minutos vs horas.

Qual a melhor categoria de evidência usar no Pagar.me?

Depende do reason code. Para "fraudulent" (Visa 10.4), use shipping_documentation + customer_signature + customer_communication. Para "product_not_received" (Visa 13.1), shipping_documentation + service_documentation. O campo uncategorized_text é sempre preenchido com sua carta de defesa.

Posso integrar com Shopify para contestação automática?

Pagar.me é o gateway de pagamento; Shopify é a plataforma. A integração é possível: você consome o webhook do Pagar.me, busca o pedido na API do Shopify, monta o pacote (NF, tracking, customer info) e submete via API do Pagar.me. Implementação típica leva 5–8 dias de dev.