Contestações

Acompanhe as contestações de pagamentos recebidos pela sua empresa, incluindo casos do Mecanismo Especial de Devolução (MED) do Pix. A API permite consultar os registros e seus resultados disponíveis.

Quando consultar uma contestação

Use a listagem para identificar casos e acompanhar suas etapas. Consulte os detalhes quando precisar do motivo, relato, resposta da empresa ou datas disponíveis. Os dados refletem o acompanhamento apresentado pela Raims; consultar a API não abre uma contestação, envia defesa, aceita uma devolução nem movimenta dinheiro.

O campo kind diferencia med, para o procedimento MED do Pix, e chargeback, para os demais registros de contestação apresentados pela Raims. Esse campo identifica o tipo do caso e deve ser considerado ao interpretar seus motivos e resultados.

Listar contestações e avançar pelas páginas

Use Listar contestações. Você pode filtrar pela cobrança, etapa, valor contestado ou intervalo de criação e escolher a ordenação por criação ou valor. O filtro de valor usa igualdade em centavos de real. As datas usam segundos Unix UTC e os limites do intervalo são inclusivos.

Comece sem cursor, processe list e copie page.next_after para after enquanto page.has_next for verdadeiro. Preserve os filtros e a ordenação durante essa navegação. Para mudar a consulta, comece novamente sem cursor.

Para voltar, use page.previous_before em before. Não envie after e before preenchidos juntos. Copie o cursor inteiro, sem interpretar ou alterar seu conteúdo. Veja Listagem e paginação.

Uma lista vazia informa que a página não contém casos que correspondam à consulta. Um filtro por cobrança não concede acesso a dados de outra empresa ou ambiente.

Consultar uma contestação

Use Recuperar uma contestação com o id recebido na listagem. Preserve o identificador completo: a API retorna IDs com prefixo dp_ ou med_ conforme o tipo de registro. charge_id identifica a cobrança vinculada, ou fica null quando não houver vínculo disponível.

O detalhe inclui relato, resposta da empresa, motivo e datas quando estiverem disponíveis. due_at é o prazo registrado para resposta, ou null quando não houver prazo informado. A presença desse campo não significa que a API aceite o envio de uma resposta.

Etapas de acompanhamento

Use stage para acompanhar o caso:

closed não significa, por si só, decisão favorável à empresa ou dinheiro devolvido. A etapa informa o andamento; os campos de resultado descrevem o que foi confirmado para aquele caso. Consultas repetidas não iniciam ou aceleram sua análise.

Motivos e resultados

Interprete reason_code junto de kind. O mesmo número pode representar motivos diferentes:

reason_code: null informa que o motivo não está disponível.

Nos casos MED, infraction_result pode ser agreed para infração reconhecida ou disagreed para infração não reconhecida. refund_result pode ser partially_accepted, totally_accepted ou rejected, conforme a análise da devolução. Esses resultados não confirmam, sozinhos, que o dinheiro foi devolvido.

refunded_amount_cents informa o total de devoluções confirmadas do caso MED. Nos registros chargeback, won_amount_cents e lost_amount_cents informam os valores de decisão favorável ou desfavorável à empresa, quando disponíveis. Cada campo fica null quando não se aplica ao tipo de caso ou quando não há resultado disponível; preserve a diferença entre null e um valor zero confirmado.

loss_reason_code, quando informado, identifica prazo de resposta expirado (1), evidências insuficientes (2), documentação inválida (3), decisão final (4) ou outro motivo (5). loss_reason_note complementa esse motivo quando houver uma observação disponível.

Empresa e ambiente

As consultas exigem uma chave de API e usam a empresa e o ambiente vinculados a ela. Uma chave Sandbox consulta somente esse ambiente; ela não acessa contestações de Produção. O console desta documentação aceita somente chaves Sandbox.

Use o identificador retornado pela Raims e trate os erros pelo status HTTP e por error.code. Nas falhas de validação, consulte também os campos indicados em error.details. A consulta individual retorna o mesmo erro quando o caso não existe ou não está disponível para a chave utilizada.