Contracargos

Contracargos

El servicio de Contracargos de Pomelo es un servicio integral diseñado para facilitar y optimizar la gestión de contracargos en transacciones de pago realizadas a través de la plataforma de Pomelo.

¿Qué es un contracargo?

Un contracargo es una solicitud de devolución de un pago realizado a través de la plataforma de Pomelo.

Estados de los contracargos

Todos los contracargos poseen el campo status, que representa en qué parte de la gestión del mismo se encuentra. Los posibles estados de un contracargo son los siguientes:

  • PENDING: El contracargo se encuentra en estado pendiente.
  • UNDER_EVALUATION: Se está realizando un primer análisis del contracargo y se necesita más información para poder continuar con la disputa.
  • DISPUTE_OPEN: La disputa de la transacción fue abierta con la marca (Mastercard o Visa) y se está esperando la respuesta de la misma.
  • DISPUTE_REJECTED: La disputa fue rechazada por la marca, ya que la transacción no cumple con los requisitos para ser disputada.
  • DISPUTE_WON: La disputa fue ganada a favor del emisor.
  • DISPUTE_LOST: La disputa fue perdida; la responsabilidad en este caso queda del lado del emisor o del tarjetahabiente.
  • 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.

Crear contracargo

El endpoint /chargebacks/v2/ permite crear un contracargo.

Validaciones

Para la creación de un contracargo, se deben cumplir las siguientes validaciones:

  • Solo puede existir un contracargo por cada transacción.
  • El campo amount debe ser mayor a 0.
  • El campo amount debe ser menor o igual al monto de la transacción.
  • La antigüedad de la transacción a la cual está asociada el contracargo no debe exceder los 90 días.

Consideraciones

Cuando se crea un contracargo de tipo CONTROVERSY, podremos agregar adjuntos para apoyar la disputa. Esto se puede hacer con el recurso

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Header de autorización
Ejemplo: `Bearer {access_token}`
Body Parameters
card_replacementboolean
Este campo representa si el usuario ha recibido ya una nueva tarjeta como remplazo de la tarjeta que reporta el contracargo
countrystring
Identificador ISO del país (puede ser un codigo de 2 o 3 letras)
descriptionstring
Una breve descripción de lo sucedido en el caso
dispute_amountnumber
Monto contracargado, de no ser especificado será de la totalidad de la transacción
dispute_typestringrequired
Tipo de disputa; FRAUD es utilizado para transacciones donde el usuario desconoce la misma, mientras que CONTROVERSY es utilizado para cuando hay un desacuerdo entre merchanty user
Enum: CONTROVERSYFRAUD
reasonstringrequired
La razón del contracargo. Los valores PHYSYCAL_PAYMENT y VIRTUAL_PAYMENT son solamente aceptados en caso de que el campo dispute_type sea FRAUD
Enum: VIRTUAL_PAYMENTPHYSICAL_PAYMENTPRODUCT_NOT_DELIVERYPURCHASE_CANCELLATIONSERVICE_NOT_PERFORMEDOTHER
transaction_idstringrequired
Identificador de la transacción a ser contracargada
trust_credit_appliedboolean
Indica si le fue dado credito en confianza o no al usuario que reporta el contracargo. Solo aplica en México
Detalle de respuestas
amountnumber
Monto del contracargo, la moneda asociada está en el campo currency_id
attachmentsarray
Lista de metadata de los archivos adjuntos
card_replacementboolean
Representa si se realizó el envio de una tarjeta de reemplazo
country_idstring
Identificador ISO del país de la transacción
Ejemplo: ARG
created_atstring
Fecha de creación del contracargo
currencystring
Moneda en la cual fue efectuada la transacción
Ejemplo: ARS
descriptionstring
Descripción brindada por el usuario al momento de la creación del contracargo
reasonstring
La razón del contracargo. Los valores PHYSYCAL_PAYMENT y VIRTUAL_PAYMENT son solamente aceptados en caso de que el campo dispute_type sea FRAUD
Enum: VIRTUAL_PAYMENTPHYSICAL_PAYMENTPRODUCT_NOT_DELIVERYPURCHASE_CANCELLATIONSERVICE_NOT_PERFORMEDOTHER
dispute_typestring
Tipo de disputa; FRAUD es utilizado para transacciones donde el usuario desconoce la misma, mientras que CONTROVERSY es utilizado para cuando hay un desacuerdo entre merchant y user
Enum: CONTROVERSYFRAUD
idstring
Identificador del contracargo
Ejemplo: `cbk-1ab2c3d4`
liabilitystring
La entidad financiera responsable de pagar el costo generado por el contracargo
Enum: MERCHANTISSUERUSERPOMELO
dispute_reasonstring
statusstring
Estado en el cual se encuentra el contracargo
Enum: PENDINGUNDER_EVALUATIONDISPUTE_OPENSECOND_PRESENTMENTDISPUTE_REJECTEDDISPUTE_WONDISPUTE_LOSTDISPUTE_NOT_PROCESSEDTRANSACTION_NOT_PRESENTED
transaction_idstring
Identificador de la transacción asociada a el contracargo
trust_credit_appliedboolean
updated_atstring
Última fecha de actualización del contracargo
user_idstring
Identificador del usuario asociado a la transacción del contracargo

¿Te resultó útil esta sección?

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
}
Ejemplo de respuestas
{
"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"
}

Adjuntar archivo a un contracargo

El endpoint /chargebacks/v2/$ID/attachments permite adjuntar un archivo a un contracargo para poder enviarlo a la marca y facilitar la disputa

Restricciones

  • El archivo adjunto debe ser una imagen o un archivo PDF.
  • El archivo adjunto debe ser menor de 3 MB.
  • Cada contracargo puede tener hasta 3 archivos adjuntos.

¿Cómo adjuntar el archivo?

El archivo debe ser adjuntado en el cuerpo de la petición como un multipart/form-data, bajo la clave fileUpload.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Header de autorización
Ejemplo: `Bearer {access_token}`
Path Parameters
chargebackIdstringrequired
Identificador del contracargo
Ejemplo: `cbk-a1b2c3d4`
Detalle de respuestas
errorboolean
infostring
msg

¿Te resultó útil esta sección?

POST/chargebacks/v2/{chargebackId}/attachments
Ejemplo de respuestas
{
"error":
true
"info":
"string"
}

Buscar contracargos

El endpoint /chargebacks/v2/ realiza una búsqueda de los contracargos del cliente. Se pueden añadir filtros para acotar los resultados de la búsqueda.

Consideraciones

Tendrás que especificar tus filtros como parámetros siguiendo este patrón: filter[field]=value. Por ejemplo: filter[status]=APPROVED

Los resultados serán paginados y podrás especificar la cantidad de datos por página y también qué página ver.

Rango de fechas

Hay un filtro para el campo created_at, que podrás usar para obtener los contracargos creados dentro de un rango de fechas. Por ejemplo: filter[created_at][from]=2022-07-27&filter[created_at][to]=2022-07-28

También se puede filtrar por la fecha de última actualización updated_at.

Ordenamiento

Podrás especificar el orden de los resultados con determinados parámetros que deberás enviar como una lista de strings en el filtro de tipo sort. Por ejemplo: ?sort=status,created_at

El ordenamiento por defecto será ascendente. Para especificar un orden descendente, deberás enviar el carácter '-' como prefijo del atributo. Por ejemplo: ?sort=status,-created_at

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Header de autorización
Ejemplo: `Bearer {access_token}`
Query Parameters
filter[user_id]string
Identificador de usuario
Ejemplo: `usr-1a2b3c`
filter[status]string
Estado de los contracargos a ser devueltos por el endpoint
Enum: PENDINGUNDER_EVALUATIONDISPUTE_OPENSECOND_PRESENTMENTDISPUTE_REJECTEDDISPUTE_WONDISPUTE_LOSTDISPUTE_NOT_PROCESSEDTRANSACTION_NOT_PRESENTED
filter[transaction_id]string
Identificador de la transacción
Ejemplo: `trx-a1b2c3d4`
Detalle de respuestas
dataarray
metaobject

¿Te resultó útil esta sección?

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

Obtener contracargo

Devuelve un contracargo con el Identificador brindado por parámetro
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Header de autorización
Ejemplo: `Bearer {access_token}`
Path Parameters
chargebackIdstringrequired
Identificador del contracargo
Ejemplo: `cbk-a1b2c3e4`
Detalle de respuestas
dataobject

¿Te resultó útil esta sección?

GET/chargebacks/v2/{chargebackId}
Ejemplo de respuestas
{
"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"
}
}