Chargebacks

Un chargeback ocurre cuando un tarjetahabiente disputa una transacción directamente con su banco, que a su vez reversa el cargo y notifica a Kushki. Como comercio, debes responder dentro de plazos estrictos para proteger tus ingresos.

Esta API te permite consultar y exportar todos los registros de chargeback asociados a tu comercio, para que puedas monitorear los casos abiertos, priorizar las respuestas por urgencia e integrar los datos de chargebacks en tus propios sistemas.

¡Ten en cuenta!

Por nuestras políticas de riesgo, los métodos de pago disponibles y el tipo de integración pueden variar una vez que completes la afiliación. Te indicaremos cómo proceder si este proceso aplica a tu comercio.

Ciclo de vida del chargeback

Cada chargeback sigue un ciclo de vida definido desde el momento en que se reporta hasta que se resuelve.

Chargeback reportado

El tarjetahabiente disputa una transacción con su banco emisor. El banco notifica a la marca de tarjeta, que traslada el chargeback a Kushki.

Kushki registra el caso y le asigna un chargeback_ticket_code y un request_date. El caso entra al sistema con estado INITIALIZED.

Notificación al comercio

Kushki te notifica el chargeback por correo (a las direcciones registradas en tu console). El campo notification_status indica si esa notificación se envió correctamente.

Desde este punto empiezan a contar dos plazos:

Plazo	Cálculo	Propósito
`deadline_representation_date`	`request_date + 15 días calendario`	Último día para presentar evidencia en tu defensa
`deadline_resolution_date`	`request_date + 120 días calendario`	Plazo máximo para la resolución final del caso

Ventana de representación

Tienes hasta deadline_representation_date para presentar documentación que defienda la transacción. Revisa el campo risk_level para priorizar en qué casos actuar primero:

`risk_level`	Condición
`HIGH`	≤ 5 días restantes hasta `deadline_representation_date`
`MEDIUM`	6 – 15 días restantes
`LOW`	> 15 días restantes

Nota: risk_level se calcula al momento de la consulta con base en la fecha actual — no se almacena de forma estática.

Resolución

La marca de tarjeta revisa la evidencia y emite un fallo final. El estado del chargeback se actualiza a uno de los siguientes estados terminales:

Estado	Significado
`APPROVAL`	El chargeback se resolvió a tu favor. El monto retenido se devuelve.
`DECLINED`	El chargeback se resolvió a favor del tarjetahabiente. El monto se debita de tu cuenta.
`NOT_MARKABLE`	El caso no se puede disputar — no se puede presentar evidencia de representación.

Tipos de chargeback

En Ecuador los chargebacks se clasifican en dos tipos, disponibles en el campo chargeback_type:

ADMINISTRATIVE

Disputas por temas de procedimiento u operación — por ejemplo, cargos duplicados, errores de procesamiento o servicios no prestados según lo acordado.

FRAUD

Disputas en las que el tarjetahabiente afirma que la transacción no fue autorizada o fue fraudulenta. Suelen tener plazos más estrictos y mayor escrutinio.

Consulta de chargebacks

La API ofrece dos métodos complementarios según tu caso de uso:

Query — Paginada (síncrona)

Export — Asíncrona (webhook)

Usa Query chargebacks (POST /data/v1/chargebacks/search) cuando necesites obtener y mostrar datos de chargebacks en tiempo real — por ejemplo, en un dashboard o en un script de monitoreo automatizado.

La respuesta es síncrona y paginada. Cada página devuelve hasta 100 registros.

Reglas del filtro time:

El objeto time es obligatorio en cada solicitud.

Envía transaction_date o request_date — nunca ambos.

El rango de fechas máximo es de 3 meses.

Ejemplo mínimo de solicitud:

{
  "filters": {
    "time": {
      "transaction_date": {
        "from": "2026-02-01",
        "to": "2026-02-28"
      }
    }
  },
  "pagination": {
    "page": 1,
    "page_size": 20
  }
}

Campos por defecto vs. opcionales

Ambos endpoints aceptan un arreglo fields para solicitar datos adicionales además de la respuesta por defecto.

Campos por defecto (siempre se devuelven)

Campos opcionales (se piden con fields[])

Campo	Descripción
`id`	Identificador único del registro de chargeback
`chargeback_ticket_code`	Número de ticket del chargeback
`merchant_name`	Nombre del comercio o de la sucursal
`chargeback_status`	Estado actual: `INITIALIZED`, `APPROVAL`, `DECLINED`, `NOT_MARKABLE`
`reason_code`	Código de motivo de la marca de tarjeta
`request_amount`	Monto de la transacción de venta original
`currency_code`	Siempre `USD` para Ecuador
`transaction_date`	Fecha de la venta original (ISO 8601 UTC)
`request_date`	Fecha en que se reportó el chargeback
`deadline_representation_date`	Plazo calculado para presentar evidencia (`request_date + 15 días`)
`deadline_resolution_date`	Plazo máximo calculado de resolución (`request_date + 120 días`)
`risk_level`	Urgencia al momento de la consulta: `HIGH`, `MEDIUM` o `LOW`

Autenticación

Todos los endpoints de chargebacks requieren tu Private Merchant ID en una cabecera de la solicitud.

Nunca expongas tu private-merchant-id en código del lado del cliente. Todas las llamadas a la API de Chargebacks deben hacerse desde tu backend.

Usa la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Consultar chargebacks

Devuelve una lista paginada de chargebacks que coinciden con los filtros aplicados. Máximo 100 registros por página.

Exportar chargebacks

Encola una exportación masiva asíncrona. Kushki envía una notificación por webhook cuando el archivo está listo para descargar.

¿Tienes alguna sugerencia sobre esta documentación? Contáctanos.

Ciclo de vida del chargeback#

Tipos de chargeback#

Consulta de chargebacks#

Campos por defecto vs. opcionales#

Autenticación#

Usa la API#

Endpoints disponibles#

Ciclo de vida del chargeback

Tipos de chargeback

Consulta de chargebacks

Campos por defecto vs. opcionales

Autenticación

Usa la API

Endpoints disponibles