Chargebacks

La API de Chargebacks te permite consultar y exportar los registros de chargebacks de tu cuenta de comercio en Chile 🇨🇱, 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": ["CHILE"]
  },
  "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	`["CHILE"]`

Valores de estado del chargeback

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

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. El body del request sigue la misma estructura que POST /data/v1/chargebacks/search, con el agregado del campo webhooks. 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": "1339b164-9298-4ea1-a52a-a9c053879194"
}

Usa el id para dar seguimiento a la solicitud o para reportar problemas de entrega al soporte de Kushki. Cuando el archivo está listo, Kushki envía por POST 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.

Exportación con filtros y campos adicionales

{
  "filters": {
    "time": {
      "request_date": {
        "from": "2026-01-15",
        "to": "2026-03-15"
     }
    },
    "chargeback_status": ["INITIALIZED"],
    "country_name": ["CHILE"]
  },
  "fields": ["ticket_code", "business_unit"],
  "webhooks": [
    "https://yoursite.com/webhooks/chargebacks",
    "https://yoursite.com/webhooks/backup"
  ]
}

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. 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

Para verificar que una notificación la envió Kushki y no un tercero, valida las siguientes cabeceras incluidas en cada llamada del webhook:

Cabecera	Descripción
`X-Kushki-Id`	Timestamp Unix (13 dígitos, milisegundos) del momento en que se envió la notificación.
`X-Kushki-Signature`	Firma HMAC SHA256 de `private-merchant-id\|request\|X-Kushki-Id`. El secreto de firma es el propio `private-merchant-id` del comercio.

Para validar la firma de tu lado, calcula:

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

Y compara el resultado con el valor recibido en X-Kushki-Signature. Si coinciden, la notificación es auténtica.

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#

Exportación con filtros y campos adicionales#

Seguridad del webhook#

Autenticación#

Uso de la API#

Endpoints disponibles#

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

Exportación con filtros y campos adicionales

Seguridad del webhook

Autenticación

Uso de la API

Endpoints disponibles