Chargebacks
Consultar chargebacks
POST /data/v1/chargebacks/searchFiltro de tiempo (obligatorio)
transaction_date o request_date dentro del objeto filters.time, no ambos. La ventana de fechas máxima permitida es de 3 meses.| Opción | Descripción |
|---|---|
transaction_date | Filtra por la fecha de la transacción de venta original |
request_date | Filtra por la fecha en que se presentó el chargeback |
from y una to en formato YYYY-MM-DD.Filtros opcionales
| Filtro | Descripción |
|---|---|
chargeback_status | Filtra por estado, ver los valores más abajo |
chargeback_type | Filtra por tipo de chargeback |
chargeback_ticket_code | Filtra por número de ticket del chargeback |
country_name | Filtra por país del comercio |
card_country_name | Filtra por el país de la tarjeta usada en la transacción |
Estados del chargeback
| Valor | Significado |
|---|---|
INITIALIZED | Chargeback recibido y en 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
| Campo | Obligatorio | Descripción |
|---|---|---|
pagination.page | ✅ | Número de página a recuperar, empezando en 1 |
pagination.page_size | ✅ | Registros por página, máximo 100 |
total y total_pages para paginar completo.Campos adicionales
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, sourceCampos de respuesta por defecto
| Campo | Descripción |
|---|---|
id | ID único del registro de chargeback |
chargeback_ticket_code | Número de ticket del chargeback |
merchant_name | Nombre del comercio |
chargeback_status | Estado actual |
reason_code | Código de motivo de la marca de tarjeta (por ejemplo, 4834, 4853) |
request_amount | Monto en disputa |
currency_code | Siempre COP para Colombia |
transaction_date | Fecha de la venta original |
request_date | Fecha en que se presentó el chargeback |
deadline_representation_date | Plazo para enviar la documentación de representación |
deadline_resolution_date | Fecha esperada de resolución |
risk_level | Nivel de riesgo asignado al chargeback: LOW, MEDIUM, HIGH |
Exportar chargebacks
POST /data/v1/chargebacks/exportfilters y fields que el endpoint de búsqueda, más un arreglo webhooks.Cómo funciona
1.
200 OK con un id único.2.
3.
POST a cada URL del arreglo webhooks con el link de descarga y su timestamp de expiración.{
"id": "1339b164-9298-4ea1-a52a-a9c053879194"
}Campo webhooks
| Campo | Obligatorio | Descripción |
|---|---|---|
webhooks | ✅ | Arreglo de URLs de callback, máximo 5 URLs |
expiration_timestamp. El link es válido por 4 horas desde su generación.Seguridad del webhook
| 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} |
HMAC-SHA256({private-merchant-id}, "{private-merchant-id}|{request}|{X-Kushki-Id}")X-Kushki-Signature. Si coinciden, la notificación es auténtica.Petición de ejemplo — Consulta
{
"filters": {
"time": {
"transaction_date": {
"from": "2026-01-01",
"to": "2026-03-31"
}
},
"chargeback_status": ["INITIALIZED"]
},
"pagination": {
"page": 1,
"page_size": 20
}
}Autenticación
Uso de la API
🟢 Producción
🧪 Sandbox (UAT)
https://api.kushkipagos.com/Endpoints disponibles
¿Tienes una sugerencia sobre esta documentación? Contáctanos.
Modified at 2026-09-11 14:48:22