Chargebacks

La API de Chargebacks te permite consultar y exportar los registros de chargebacks de tu cuenta de comercio en México 🇲🇽, directamente por API y sin entrar a la Kushki Console.

Hay dos operaciones disponibles:

Operación	Endpoint	Descripción
Búsqueda	`POST /data/v1/chargebacks/search`	Lista paginada de chargebacks con filtros
Exportación	`POST /data/v1/chargebacks/export`	Exportación asíncrona — Kushki envía por POST el link de descarga a tu webhook cuando está listo

Buscar chargebacks

Devuelve una lista paginada de chargebacks que coinciden con tus filtros.

Request mínimo — por fecha de transacción

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

Request con filtros y campos adicionales

{
  "filters": {
    "time": {
      "request_date": {
        "from": "2026-01-15",
        "to": "2026-03-15"
      }
    },
    "chargeback_status": ["INITIALIZED"],
    "country_name": ["MEXICO"]
  },
  "fields": [
    "ticket_code",
    "business_unit",
    "chargeback_type"
  ],
  "pagination": {
    "page": 1,
    "page_size": 20
  }
}

Referencia de filtros

Filtro de tiempo (obligatorio)

Usa transaction_date (la fecha del pago original) o request_date (la fecha en que se presentó el chargeback), pero no las dos.

Campo	Descripción
`time.transaction_date.from` / `to`	Filtra por la fecha de la transacción original (`YYYY-MM-DD`)
`time.request_date.from` / `to`	Filtra por la fecha de solicitud del chargeback (`YYYY-MM-DD`)

Filtros opcionales

Filtro	Tipo	Descripción
`chargeback_status`	array	Uno o más valores de estado — ve la tabla de abajo
`chargeback_type`	array	Tipo de chargeback
`ticket_code`	array	Código de ticket de Kushki de la transacción original
`chargeback_ticket_code`	array	Código de ticket propio del chargeback
`country_name`	array	`["MEXICO"]`

Valores de estado del chargeback

Estado	Descripción
`INITIALIZED`	Chargeback creado — pendiente de revisión
`IN_PROCESS`	En revisión por parte del banco o de la red
`WON`	Disputa resuelta a favor del comercio
`LOST`	Disputa resuelta a favor del tarjetahabiente
`CANCELLED`	Chargeback cancelado

Campos adicionales

Por defecto, la respuesta de búsqueda incluye un conjunto estándar de campos. Usa el array fields para pedir datos adicionales:

Campo	Descripción
`ticket_code`	Código de ticket de la transacción original
`chargeback_ticket_code`	Código de ticket propio del chargeback
`business_unit`	Unidad de negocio asociada al comercio
`chargeback_type`	Tipo de chargeback presentado

Exportar chargebacks

Inicia una exportación asíncrona de registros de chargebacks. Kushki procesa la exportación en segundo plano y envía una notificación POST a cada URL del array webhooks cuando el archivo está listo, incluyendo el link de descarga y su timestamp de expiración.

Exportación básica

{
  "filters": {
    "time": {
      "request_date": {
        "from": "2026-01-15",
        "to": "2026-03-15"
      }
    }
  },
  "webhooks": [
    "https://yoursite.com/webhooks/chargebacks"
  ]
}

Respuesta:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Cuando el archivo está listo, Kushki envía por POST a tu URL de webhook:

{
  "exportId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "downloadUrl": "https://storage.kushkipagos.com/exports/chargebacks-2026-05-29.csv",
  "expiresAt": "2026-05-30T12:00:00Z"
}

Exportación asíncrona

El endpoint de exportación responde de inmediato con un id. El archivo se genera de forma asíncrona: tu webhook recibe el link de descarga cuando está listo. Diseña tu manejador de webhooks para que sea idempotente en caso de reintentos de entrega.

Autenticación

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Consultar chargebacks

Búsqueda paginada con filtros por fecha, estado, tipo y código de ticket.

Solicitar exportación de chargebacks

Exportación asíncrona — responde de inmediato con un ID de trabajo. El link de descarga se entrega a tu URL de webhook.

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

Buscar chargebacks#

Request mínimo — por fecha de transacción#

Request con filtros y campos adicionales#

Referencia de filtros#

Filtro de tiempo (obligatorio)#

Filtros opcionales#

Valores de estado del chargeback#

Campos adicionales#

Exportar chargebacks#

Exportación básica#

Autenticación#

Uso de la API#

Endpoints disponibles#