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, sin entrar a la Kushki Console. Es el mismo servicio de Chargebacks disponible en Online Payments, expuesto aquí para los comercios que integran solo presencial.

Hay dos operaciones disponibles:

Operación	Endpoint	Descripción
Search	`POST /data/v1/chargebacks/search`	Lista paginada de chargebacks con filtros
Export	`POST /data/v1/chargebacks/export`	Exportación asíncrona — Kushki hace un POST con el link de descarga a tu webhook cuando esté listo

Consultar chargebacks

Devuelve una lista paginada de los 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)

Envía o transaction_date o request_date dentro de filters.time — no ambos. La ventana de fechas máxima permitida es de 3 meses.

Campo	Descripción
`time.transaction_date.from` / `to`	Filtra por la fecha de la transacción de venta original (`YYYY-MM-DD`)
`time.request_date.from` / `to`	Filtra por la fecha en que se presentó el chargeback (`YYYY-MM-DD`)

Filtros opcionales

Filtro	Tipo	Descripción
`chargeback_status`	array	Uno o más valores de estado — ver la tabla de abajo
`chargeback_type`	array	`ADMINISTRATIVE` o `FRAUD`
`chargeback_ticket_code`	string	Número de ticket propio del chargeback
`country_name`	array	País del comercio. Para México: `["MEXICO"]`
`card_country_name`	array	País de la tarjeta usada en la transacción

Valores del estado del chargeback

Estado	Descripción
`INITIALIZED`	Chargeback recibido — pendiente de revisión
`APPROVAL`	Chargeback resuelto a favor del tarjetahabiente
`DECLINED`	Chargeback resuelto a favor del comercio
`NOT_MARKABLE`	El chargeback no se puede disputar

Paginación (obligatoria)

Campo	Descripción
`pagination.page`	Número de página, empezando en `1`
`pagination.page_size`	Registros por página — máximo 100

La respuesta incluye total y total_pages para paginar completo.

Campos adicionales

Por defecto, la respuesta incluye un conjunto estándar de campos por chargeback. Usa el array fields para solicitar campos adicionales:

ticket_code, operation_id, transaction_reference, merchant_code, business_unit, product_code, product_description, approved_transaction_amount, transaction_type, transaction_status, chargeback_type, reason_description, notification_status, documentation_reception_date, execution_date, issuing_delivery_date, create_timestamp, update_timestamp, processor_name, issuing_bank, card_country_name, country_name, security_service, security_message, masked_credit_card, last_four_digit_code, source

Campos de respuesta por defecto

Campo	Descripción
`id`	ID único del registro del chargeback
`chargeback_ticket_code`	Número de ticket del chargeback. Puede ser `NO_INFO` cuando no está disponible
`merchant_name`	Nombre del comercio o de la sucursal asociada a la transacción
`chargeback_status`	Estado actual — ver la tabla de arriba
`reason_code`	Código de motivo de la red de tarjetas (por ejemplo, `4834`, `4853`)
`request_amount`	Monto disputado en la transacción de venta original
`currency_code`	Código de moneda ISO 4217. Para México: `MXN`
`transaction_date`	Fecha y hora de la venta original (ISO 8601 UTC)
`request_date`	Fecha en que el chargeback se reportó a la red de tarjetas o al procesador
`deadline_representation_date`	Calculado. `request_date` + 15 días calendario
`deadline_resolution_date`	Calculado. `request_date` + 120 días calendario
`risk_level`	Calculado. `HIGH` (≤5 días para la fecha límite), `MEDIUM` (6–15 días) o `LOW` (>15 días)

Exportar chargebacks

Inicia una exportación asíncrona de los registros de chargebacks. El request acepta los mismos filters y fields que el endpoint de búsqueda, más un array webhooks.

Cómo funciona

Envía el request — recibes de inmediato un 200 OK con un id único.

Kushki genera el archivo en segundo plano.

Cuando esté listo, Kushki envía una notificación POST a cada URL de webhooks con 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": "1339b164-9298-4ea1-a52a-a9c053879194"
}

Usa el id para hacer seguimiento del request o para reportar problemas de entrega al soporte de Kushki. Cuando el archivo esté listo, Kushki hace un POST con el siguiente payload a cada URL de webhook configurada:

{
  "id": "1339b164-9298-4ea1-a52a-a9c053879194",
  "request": {
    "filters": {
      "time": {
        "request_date": {
          "from": "2026-01-15",
          "to": "2026-03-15"
        }
      }
    },
    "fields": ["ticket_code", "business_unit"]
  },
  "file_url": "https://s3.amazonaws.com/kushki-chargebacks/export_abc123.csv?X-Amz-Expires=14400",
  "expiration_timestamp": 1742318400000
}

Ventana de descarga de 4 horas

file_url es una URL prefirmada de S3 válida por 4 horas desde el momento de la generación. Revisa expiration_timestamp (timestamp Unix, en milisegundos) antes de intentar la descarga.

Campo	Obligatorio	Descripción
`webhooks`	Sí	Array de URLs de callback — máximo 5

Exportación asíncrona

webhooks acepta un máximo de 5 URLs. Diseña tu manejador de webhooks para que sea idempotente en caso de reintentos de entrega.

Seguridad del webhook

Valida estas cabeceras en cada notificación para confirmar que viene de Kushki:

Cabecera	Descripción
`X-Kushki-Id`	Timestamp Unix (en milisegundos) del momento en que se envió la notificación
`X-Kushki-Signature`	Firma HMAC-SHA256 de `{private-merchant-id}\|{request}\|{X-Kushki-Id}`

Para validar de tu lado, calcula:

HMAC-SHA256({private-merchant-id}, "{private-merchant-id}|{request}|{X-Kushki-Id}")

Compara el resultado con X-Kushki-Signature. Si coinciden, la notificación es auténtica.

Autenticación

Usar 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 — devuelve de inmediato un ID de trabajo. El link de descarga llega a la URL de tu webhook.

¿Tienes una sugerencia sobre esta documentación? Escríbenos.

Consultar 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 del estado del chargeback#

Paginación (obligatoria)#

Campos adicionales#

Campos de respuesta por defecto#

Exportar chargebacks#

Cómo funciona#

Exportación básica#

Seguridad del webhook#

Autenticación#

Usar la API#

Endpoints disponibles#

Consultar 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 del estado del chargeback

Paginación (obligatoria)

Campos adicionales

Campos de respuesta por defecto

Exportar chargebacks

Cómo funciona

Exportación básica

Seguridad del webhook

Autenticación

Usar la API

Endpoints disponibles