Chargebacks

La API de Chargebacks te permite consultar y exportar los registros de chargebacks de tu cuenta de comercio en Colombia 🇨🇴 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 solo integran Card Present.

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 los chargebacks que coinciden con tus filtros.

Solicitud mínima: por fecha de transacción

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

Solicitud con filtros y campos adicionales

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

Referencia de filtros

Filtro de tiempo (requerido)

Envía solo uno de 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; revisa la tabla de abajo
`chargeback_type`	array	`ADMINISTRATIVE` or `FRAUD`
`chargeback_ticket_code`	string	Número de ticket propio del chargeback
`country_name`	array	País del comercio. Para Colombia: `["COLOMBIA"]`
`card_country_name`	array	País de la tarjeta usada en la transacción

Valores de 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 controvertir

Paginación (requerida)

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

Campos adicionales

Por defecto, la respuesta incluye un conjunto estándar de campos por chargeback. Usa el arreglo 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 la respuesta por defecto

Campo	Descripción
`id`	ID único del registro de chargeback
`chargeback_ticket_code`	Número de ticket del chargeback. Puede ser `NO_INFO` cuando no está disponible
`merchant_name`	Nombre del comercio o sucursal asociada a la transacción
`chargeback_status`	Estado actual; revisa la tabla de arriba
`reason_code`	Código de razón de la marca de tarjeta (por ejemplo, `4834`, `4853`)
`request_amount`	Monto controvertido en la transacción de venta original
`currency_code`	Código de moneda ISO 4217. Para Colombia: `COP`
`transaction_date`	Fecha y hora de la venta original (ISO 8601 UTC)
`request_date`	Fecha en que el chargeback se reportó a la marca de tarjeta 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. La solicitud acepta los mismos filters y fields que el endpoint de búsqueda, más un arreglo webhooks.

Cómo funciona

Envía la solicitud: 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 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 pre-firmada 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	Requerido	Descripción
`webhooks`	Sí	Arreglo de URLs de callback; máximo 5

Exportación asíncrona

webhooks acepta un máximo de 5 URLs. Diseña tu manejador de webhook 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 (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

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 número de ticket.

Solicitar exportación de chargebacks

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

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

Buscar chargebacks#

Solicitud mínima: por fecha de transacción#

Solicitud con filtros y campos adicionales#

Referencia de filtros#

Filtro de tiempo (requerido)#

Filtros opcionales#

Valores de estado del chargeback#

Paginación (requerida)#

Campos adicionales#

Campos de la respuesta por defecto#

Exportar chargebacks#

Cómo funciona#

Exportación básica#

Seguridad del webhook#

Autenticación#

Uso de la API#

Endpoints disponibles#

Buscar chargebacks

Solicitud mínima: por fecha de transacción

Solicitud con filtros y campos adicionales

Referencia de filtros

Filtro de tiempo (requerido)

Filtros opcionales

Valores de estado del chargeback

Paginación (requerida)

Campos adicionales

Campos de la respuesta por defecto

Exportar chargebacks

Cómo funciona

Exportación básica

Seguridad del webhook

Autenticación

Uso de la API

Endpoints disponibles