Chargebacks

Chargebacks

O serviço de Chargebacks da Pomelo é um serviço integrado projetado para facilitar e otimizar a gestão de disputas em transações de pagamento realizadas através da plataforma da Pomelo.

O qué é um chargeback?

Um chargeback é uma solicitação de reembolso de um pagamento feito através da plataforma Pomelo.

Status dos chargebacks

Todos os chargebacks possuem o campo status que indica en qué parte da sua gestão eles estão. Os possíveis status de um chargeback são os seguintes:

  • PENDING: O status do chargeback está pendente.
  • UNDER_EVALUATION: Uma primeira análise do chargeback está em curso e mais informações são necessárias a fim de continuar a disputa.
  • DISPUTE_OPEN: A disputa da transação foi iniciada com a marca (Mastercard ou Visa) e estamos aguardando a resposta deles.
  • DISPUTE_REJECTED: A disputa foi rejeitada pela marca, pois a transação não atendeu aos requisitos necessários para ser contestada.
  • DISPUTE_WON: A disputa fui ghana em favor do emissor.
  • DISPUTE_LOST: A disputa foi perdida; neste caso, a responsabilidade recai sobre o emissor ou titular do cartão.
  • DISPUTE_NOT_PROCESSED: No pudimos procesar el contracargo dadas las características del pago.
  • TRANSACTION_NOT_PRESENTED: La transacción aún no ha sido presentada por el adquirente, por lo que no es posible solicitar un contracargo.

Criar chargeback

O endpoint /chargebacks/v2/ permite criar um chargeback.

Validações

Para a criação de um chargeback, as seguintes validações têm de ser cumpridas:

  • Só pode existir um pedido de contestação por transação.
  • O campo amount deve ser maior do que 0.
  • O campo amount deve ser menor ou igual ao montante da transação.
  • A transação associada ao chargeback deve ter ocorrido há menos de 90 dias.

Considerações

Ao criar um chargeback do tipo CONTROVERSY, podemos incluir anexos para apoiar a disputa. Nesse caso, utilizar o recurso /chargebacks/v2/{chargebackId}/attachments

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Header de autorização
Exemplo: `Bearer {access_token}`
Body Parameters
card_replacementboolean
Este campo representa se o usuário já recebeu um novo cartão como substituto do cartão que para o cartão que reporta o chargeback.
countrystring
Identificador de país ISO (pode ser um código de 2 ou 3 letras)
descriptionstring
Uma breve descrição do que aconteceu no caso
dispute_amountnumber
Valor do chargeback, se não for especificado, será o valor total da transação.
dispute_typestringrequired
Tipo de disputa; FRAUD é usado para transações em que o usuário desconhece a transação, enquanto CONTROVERSY é usado quando há um desentendimento entre comerciante e usuário
Enum: CONTROVERSYFRAUD
reasonstringrequired
O motivo do chargeback. Os valores PHYSICAL_PAYMENT e VIRTUAL_PAYMENT só são aceitos no caso do campo dispute_type ser FRAUD
Enum: VIRTUAL_PAYMENTPHYSICAL_PAYMENTPRODUCT_NOT_DELIVERYPURCHASE_CANCELLATIONSERVICE_NOT_PERFORMEDOTHER
transaction_idstringrequired
Identificador da transação com chargeback
trust_credit_appliedboolean
Indica se foi dado crédito em confiança ou não ao usuário que reporta o chargeback. Aplica-se apenas no México
Detalhe de respostas
amountnumber
Valor do chargeback, a moeda associada está no campo currency_id
attachmentsarray
Lista de metadados dos arquivos anexos
card_replacementboolean
Representa se foi enviado um cartão substituto
country_idstring
Identificador ISO do país associado à transação
Exemplo: ARG
created_atstring
Data de criação do chargeback
currencystring
Moeda em que a transação foi feita
Exemplo: ARS
descriptionstring
Descrição fornecida pelo usuário no momento da criação do chargeback
reasonstring
O motivo do chargeback. Os valores PHYSICAL_PAYMENT e VIRTUAL_PAYMENT só são aceitos no caso do campo dispute_type ser FRAUD
Enum: VIRTUAL_PAYMENTPHYSICAL_PAYMENTPRODUCT_NOT_DELIVERYPURCHASE_CANCELLATIONSERVICE_NOT_PERFORMEDOTHER
dispute_typestring
Tipo de disputa; FRAUD é utilizado para transações em que o usuário não reconhece a mesma, enquanto CONTROVERSY é utilizado quando há um desacordo entre o merchant e o user
Enum: CONTROVERSYFRAUD
idstring
Identificador do chargeback
Exemplo: `cbk-1ab2c3d4`
liabilitystring
A entidade financeira responsável pelo pagamento do custo gerado pelo chargeback
Enum: MERCHANTISSUERUSERPOMELO
dispute_reasonstring
statusstring
Status em que se encontra o chargeback
Enum: PENDINGUNDER_EVALUATIONDISPUTE_OPENSECOND_PRESENTMENTDISPUTE_REJECTEDDISPUTE_WONDISPUTE_LOSTDISPUTE_NOT_PROCESSEDTRANSACTION_NOT_PRESENTED
transaction_idstring
Identificador da transação associada ao chargeback
trust_credit_appliedboolean
updated_atstring
Última data de atualização do chargeback
user_idstring
Identificador do usuário associado à transação do chargeback

Esta seção foi útil para você?

POST/chargebacks/v2
{
"card_replacement":
true
"country":
"string"
"description":
"string"
"dispute_amount":
"number"
"dispute_type":
"CONTROVERSY"
"reason":
"VIRTUAL_PAYMENT"
"transaction_id":
"string"
"trust_credit_applied":
true
}
Respostas de amostra
{
"amount":
"number"
"attachments":[
0:{
...
}
]
"card_replacement":
true
"country_id":
"ARG"
"created_at":
"string"
"currency":
"ARS"
"description":
"string"
"reason":
"VIRTUAL_PAYMENT"
"dispute_type":
"CONTROVERSY"
"id":
"`cbk-1ab2c3d4`"
"liability":
"MERCHANT"
"dispute_reason":
"string"
"status":
"PENDING"
"transaction_id":
"string"
"trust_credit_applied":
true
"updated_at":
"string"
"user_id":
"string"
}

Anexar um arquivo a um chargeback

O endpoint /chargebacks/v2/$ID/attachments permite a anexação de arquivos a um chargeback a fim de enviá-lo à marca e simplificar a resolução de disputas

Restrições

  • O arquivo anexo deve ser uma imagem ou um PDF.
  • O arquivo anexo deve ser menor do que 3 MB.
  • Cada chargeback pode ter até 3 arquivos anexados.

Como anexar o arquivo?

O arquivo deve ser anexado no corpo do pedido como um multipart/form-data, sob a chave fileUpload.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Header de autorização
Exemplo: `Bearer {access_token}`
Path Parameters
chargebackIdstringrequired
Identificador do chargeback
Exemplo: `cbk-a1b2c3d4`
Detalhe de respostas
errorboolean
infostring
msg

Esta seção foi útil para você?

POST/chargebacks/v2/{chargebackId}/attachments
Respostas de amostra
{
"error":
true
"info":
"string"
}

Procurar chargebacks

O endpoint /chargebacks/v2/ realiza uma busca por chargebacks de clientes. Os filtros podem ser adicionados para adequar os resultados da busca.

Considerações

Será necessário especificar os filtros desejados como parâmetros de acordo com o seguinte padrão: filter[field]=value. Por exemplo: filter[status]=APPROVED

Os resultados serão fornecidos por página. É possível especificar a quantidade de dados por página e também qual página se deseja visualizar.

Período

Há um filtro para o campo created_atque você pode utilizar se quiser obter os chargebacks criados dentro de uma faixa de datas específica. Por exemplo: filter[created_at][from]=2022-07-27&filter[created_at][to]=2022-07-28

Também é possível filtrar pela última data de atualização utilizando updated_at.

Ordenação

É possível especificar a ordem dos resultados com certos parâmetros que deverão ser enviados como uma lista de strings no filtro do tipo sort. Por exemplo: ?sort=status,created_at

A ordenação padrão será crescente. Para especificar uma ordem decrescente, deve-se enviar o caractere '-' como prefixo do atributo. Por exemplo: ?sort=status,-created_at

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Header de autorização
Exemplo: `Bearer {access_token}`
Query Parameters
filter[user_id]string
Identificador de usuário
Exemplo: `usr-1a2b3c`
filter[status]string
Status dos chargebacks a serem retornados pelo endpoint
Enum: PENDINGUNDER_EVALUATIONDISPUTE_OPENSECOND_PRESENTMENTDISPUTE_REJECTEDDISPUTE_WONDISPUTE_LOSTDISPUTE_NOT_PROCESSEDTRANSACTION_NOT_PRESENTED
filter[transaction_id]string
Identificador da transação
Exemplo: `trx-a1b2c3d4`
Detalhe de respostas
dataarray
metaobject

Esta seção foi útil para você?

GET/chargebacks/v2/
Respostas de amostra
{
"data":[
0:{
...
}
]
"meta":{
"filter":[
...
]
"pagination":{
...
}
}
}

Obter chargeback

Retorna um chargeback com o identificador fornecido como parâmetro
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Header de autorização
Exemplo: `Bearer {access_token}`
Path Parameters
chargebackIdstringrequired
Identificador do chargeback
Exemplo: `cbk-a1b2c3e4`
Detalhe de respostas
dataobject

Esta seção foi útil para você?

GET/chargebacks/v2/{chargebackId}
Respostas de amostra
{
"data":{
"amount":
"number"
"attachments":[
...
]
"card_replacement":
true
"country_id":
"ARG"
"created_at":
"string"
"currency":
"ARS"
"description":
"string"
"reason":
"VIRTUAL_PAYMENT"
"dispute_type":
"CONTROVERSY"
"id":
"`cbk-1ab2c3d4`"
"liability":
"MERCHANT"
"dispute_reason":
"string"
"status":
"PENDING"
"transaction_id":
"string"
"trust_credit_applied":
true
"updated_at":
"string"
"user_id":
"string"
}
}