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"
}
}

Notificaciones de chargebacks

Este servicio será el encargado de notificarte cuando se modifique un contracargo.

Si tienes dudas sobre cómo configurar un webhook, visita nuestra documentación.

También puedes encontrar más información sobre el Proceso de verificación de la firma digital.

Parámetros disponibles
Header Parameters
X-Api-Keystringrequired
Este header te permitirá identificar qué api-secret tenés que usar en el caso que se hayan configurado múltiples pares de api-key y api-secret.
Ejemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
Este header contiene la firma digital (timestamp + endpoint + body) que deberás verificar para asegurar la integridad del request. Si la firma no coincide, deberás rechazar el pedido.
Ejemplo: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
Este header contiene el momento en el que se firmó el pedido en formato unix-epoch para que puedas corroborar que la firma no expiró.
Ejemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
El endpoint al que se realiza el pedido y usaste para generar la firma. Usa este header para regenerar la firma a validar, compararlo con el endpoint de tu servicio y verificar que coinciden.
Ejemplo: X-Endpoint: /client/api/chargeback/done
Body Parameters
event_idstringrequired
Identificador de evento.
Ejemplo: chargeback_notification
Enum: chargeback_notification
idempotency_keystringrequired
Identificador idempotente de creación del evento.
Ejemplo: 27Ky00tAZ0Rdi7G2Vt9iino8AYs
transaction_idstringrequired
Identificador de la transacción a ser contracargada
Ejemplo: ctx-1a2b3c4b
statusstringrequired
Estado del Contracargo
Ejemplo: PENDING
Enum: PENDINGUNDER_EVALUATIONDISPUTE_OPENSECOND_PRESENTMENTDISPUTE_REJECTEDDISPUTE_WONDISPUTE_LOSTDISPUTE_NOT_PROCESSEDTRANSACTION_NOT_PRESENTED
status_ticketstringrequired
Estado del Ticket del Contracargo
Ejemplo: DONE
Enum: WAITING_FOR_SUPPORTWAITING_FOR_CUSTOMERESCALATEDDONECLOSED
idstringrequired
Identificador del contracargo
Ejemplo: cbk-1a2b3c
amountnumberrequired
Monto del contracargo.
Ejemplo: 10
currencystringrequired
Moneda del contracargo.
Ejemplo: ARS
countrystringrequired
País del contracargo.
Ejemplo: ARG
client_idstringrequired
Cliente del contracargo.
Ejemplo: cli-1a2b3c
liabilitystringrequired
La entidad financiera responsable de pagar el costo generado por el contracargo
Enum: MERCHANTISSUERUSERPOMELO
created_atstringrequired
Fecha de creación del contracargo

¿Te resultó útil esta sección?

POST/chargebacks/<session-event-client-url>
{
"event_id":
"chargeback_notification"
"idempotency_key":
"27Ky00tAZ0Rdi7G2Vt9iino8AYs"
"transaction_id":
"ctx-1a2b3c4b"
"status":
"PENDING"
"status_ticket":
"DONE"
"id":
"cbk-1a2b3c"
"amount":
10
"currency":
"ARS"
"country":
"ARG"
"client_id":
"cli-1a2b3c"
"liability":
"MERCHANT"
"created_at":
"string"
}
Ejemplo de respuestas