Chargeback

Entenda os campos status e reason retornados no objeto chargeback e como interpretá-los na integração.

Entenda como interpretar as informações retornadas no campo chargeback quando uma cobrança entra em processo de chargeback.

O objeto chargeback ajuda sua integração a identificar a situação atual da contestação e o motivo informado para ela. Use essas informações para acompanhar cobranças contestadas, atualizar fluxos internos de atendimento e orientar processos de conciliação.

Campos relevantes

Campo	Tipo	Descrição
`chargeback.status`	`string`	Indica a etapa atual do chargeback. Esse é o campo principal para decidir como sua integração deve tratar a cobrança contestada.
`chargeback.reason`	`string`	Indica o motivo do chargeback. Use esse campo para classificar o cenário operacional e direcionar a análise interna.

Status do chargeback

O campo chargeback.status pode retornar os seguintes valores:

Valor	Descrição
`REQUESTED`	Chargeback solicitado.
`IN_DISPUTE`	Chargeback em disputa.
`DISPUTE_LOST`	Disputa perdida.
`REVERSED`	Chargeback revertido.
`DONE`	Processo de chargeback concluído.

Motivos do chargeback

O campo chargeback.reason pode retornar os seguintes valores:

Valor	Descrição
`ABSENCE_OF_PRINT`	Ausência de impressão.
`ABSENT_CARD_FRAUD`	Fraude em ambiente de cartão não presente.
`CARD_ACTIVATED_PHONE_TRANSACTION`	Transação telefônica ativada por cartão.
`CARD_FRAUD`	Fraude em ambiente de cartão presente.
`CARD_RECOVERY_BULLETIN`	Boletim de negativação de cartões.
`COMMERCIAL_DISAGREEMENT`	Desacordo comercial.
`COPY_NOT_RECEIVED`	Cópia não atendida.
`CREDIT_OR_DEBIT_PRESENTATION_ERROR`	Erro de apresentação de crédito / débito.
`DIFFERENT_PAY_METHOD`	Pagamento por outros meios.
`FRAUD`	Sem autorização do portador do cartão.
`INCORRECT_TRANSACTION_VALUE`	Valor da transação é diferente.
`INVALID_CURRENCY`	Moeda inválida.
`INVALID_DATA`	Dados inválidos.
`LATE_PRESENTATION`	Apresentação tardia.
`LOCAL_REGULATORY_OR_LEGAL_DISPUTE`	Contestação regulatória / legal local.
`MULTIPLE_ROCS`	ROCs múltiplos.
`ORIGINAL_CREDIT_TRANSACTION_NOT_ACCEPTED`	Transação de crédito original não aceita.
`OTHER_ABSENT_CARD_FRAUD`	Outras fraudes - Cartão ausente.
`PROCESS_ERROR`	Erro de processamento.
`RECEIVED_COPY_ILLEGIBLE_OR_INCOMPLETE`	Cópia atendida ilegível / incompleta.
`RECURRENCE_CANCELED`	Recorrência cancelada.
`REQUIRED_AUTHORIZATION_NOT_GRANTED`	Autorização requerida não obtida.
`RIGHT_OF_FULL_RECOURSE_FOR_FRAUD`	Direito de regresso integral por fraude.
`SALE_CANCELED`	Mercadoria / serviços cancelado.
`SERVICE_DISAGREEMENT_OR_DEFECTIVE_PRODUCT`	Mercadoria / serviço com defeito ou em desacordo.
`SERVICE_NOT_RECEIVED`	Mercadoria / serviços não recebidos.
`SPLIT_SALE`	Desmembramento de venda.
`TRANSFERS_OF_DIVERSE_RESPONSIBILITIES`	Transf. de responsabilidades diversas.
`UNQUALIFIED_CAR_RENTAL_DEBIT`	Débito de aluguel de carro não qualificado.
`USA_CARDHOLDER_DISPUTE`	Contestação do portador de cartão (EUA).
`VISA_FRAUD_MONITORING_PROGRAM`	Programa Visa de monitoramento de fraude.
`WARNING_BULLETIN_FILE`	Arquivo boletim de advertência.

Comportamento na integração

Verifique se o objeto chargeback foi retornado na cobrança.
Leia chargeback.status para identificar a situação atual do chargeback.
Leia chargeback.reason para entender o motivo informado.
Atualize seus controles internos usando os valores exatos retornados pela API.

Exemplo simplificado de retorno com chargeback:

{
  "chargeback": {
    "status": "IN_DISPUTE",
    "reason": "COMMERCIAL_DISAGREEMENT"
  }
}

Nesse exemplo, a cobrança possui um chargeback em disputa (IN_DISPUTE) causado por desacordo comercial (COMMERCIAL_DISAGREEMENT).

Cuidados

Compare os valores de status e reason exatamente como retornados pela API, sem adicionar espaços, alterar maiúsculas ou traduzir os enums no código.
Use chargeback.status para controlar o andamento do chargeback. Use chargeback.reason apenas para classificar o motivo da contestação.
Trate valores não mapeados de forma segura, mantendo o valor original em logs ou registros internos para análise posterior.
Revise cobranças com motivos relacionados a fraude, desacordo comercial, serviço não recebido ou valor incorreto com atenção, pois esses cenários costumam exigir análise operacional.

Para saber mais sobre Chargeback, clique aqui.