Estornos e disputas

Pedir um estorno

Estorne uma cobrança confirmada ou recebida, total ou parcialmente. O reason é interno (não vai ao provedor): não coloque dados pessoais nele. A resposta é uma Operation cujo resourceId é o estorno.

{
  "amountCents": "4990",
  "reason": "Cliente desistiu da compra dentro do prazo."
}

{
  "id": "op_01JDY8D1B2C3D4E5F6G7H8J9KD",
  "status": "ACCEPTED",
  "kind": "REFUND_PAYMENT",
  "resourceId": "rfd_01JDYA11B2C3D4E5F6G7H8J9KA",
  "statusUrl": "/v1/operations/op_01JDY8D1B2C3D4E5F6G7H8J9KD",
  "nextAction": "WAIT",
  "createdAt": "2026-11-13T13:00:00.000Z"
}

• Limite elegível: pago − devolvido − reservado. Pedidos simultâneos nunca passam do total (422 REFUND_EXCEEDS_ELIGIBLE).
• Cobrança já recebida só estorna até o saldo disponível conciliado da conta (a tarifa do provedor não volta): acima dele, 422 INSUFFICIENT_AVAILABLE_BALANCE e nada é criado.
• Pix e cartão aceitam estorno parcial. Cartão parcelado é estornado pelo parcelamento (um estorno ativo por vez, REFUND_IN_PROGRESS). Boleto só integral (PARTIAL_REFUND_NOT_SUPPORTED) e o pagador informa a conta de devolução no link payerActionUrl do estorno.
• Cobrança pendente, em disputa ou já estornada por inteiro não estorna (PAYMENT_NOT_REFUNDABLE).
• Use uma Idempotency-Key por intenção (por exemplo pedido-98765-estorno-1). Um 422 é conclusivo e não fica gravado: corrigida a causa, a mesma chave pode ser usada de novo.

Situações do estorno

Estornos feitos fora do Eclipta Pay (por exemplo, no painel do provedor) são descobertos na consulta e aparecem em GET /v1/payments/{id}/refunds com origin: "PROVIDER". O pedido passa por REFUND_PENDING enquanto há estorno em andamento.

Disputas (chargebacks)

A disputa nasce do emissor do cartão: o provedor avisa e a plataforma abre o registro com motivo, valor e prazo da defesa. A cobrança continua com o histórico (por exemplo RECEIVED) e a dimensão de reversão vira DISPUTED; o pedido passa a DISPUTED e fulfillmentEligible volta a false.

1. Acompanhe pelo evento payment.dispute_updated e por GET /v1/disputes/{id} (reason original e reasonLabel em português, evidenceDueBy).
2. Anexe evidências com POST /v1/disputes/{id}/evidence: corpo binário (PDF, JPG ou PNG até 10 MB) e o nome em X-File-Name. Os arquivos ficam cifrados em armazenamento privado da conta.
3. Envie a defesa uma única vez com POST /v1/disputes/{id}/submit e a versão esperada (202). Depois do envio não é possível anexar mais nada (DISPUTE_NOT_OPEN).
4. Desfecho: ganha (WON) restaura a cobrança e o pedido volta a PAYMENT_COMPLETED; perdida (LOST) deixa a reversão em CHARGED_BACK e o pedido segue DISPUTED, sem virar "estornado".

curl -X POST "$ECLIPTA_PAY_API/v1/disputes/dsp_.../evidence" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT" \
  -H "Idempotency-Key: disputa-dsp_...-comprovante-1" \
  -H "Content-Type: application/pdf" \
  -H "X-File-Name: comprovante-entrega.pdf" \
  --data-binary @comprovante-entrega.pdf

Estorno de pagamento com dois cartões

POST /v1/payment-groups/{id}/refunds divide o valor entre os dois cartões de forma proporcional (maiores restos, com teto por cartão), grava a divisão antes do envio e confirma cada parte separadamente. Veja Dois cartões e planos.

Rotas

A integração de referência do Educators mostra o cancelamento dentro da garantia (estorno, acesso suspenso até DONE) e a revisão do acesso numa disputa.