Solicitar exportación de chargebacks

Inicia la generación asíncrona de un archivo de exportación de chargebacks.

Al recibir la solicitud, el sistema devuelve de inmediato una respuesta 200 OK con un id único. Una vez generado y almacenado el archivo, Kushki envía una notificación POST a cada URL configurada en el arreglo webhooks, con el link de descarga y su timestamp de expiración.

El cuerpo de la solicitud tiene la misma estructura que POST /data/v1/chargebacks/search, más el campo webhooks.

Nota: La URL de descarga es una URL pre-firmada de S3 válida por 4 horas desde el momento de la generación. Revisa expiration_timestamp en la notificación del webhook antes de intentar la descarga.

Seguridad del webhook

Para verificar que una notificación la envió Kushki y no un tercero, valida las siguientes cabeceras que vienen 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}")

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

Responses

🟢200OK

application/json

Solicitud aceptada. La exportación quedó en cola para procesarse. Se enviará una notificación del webhook a cada URL configurada cuando el archivo esté listo para descargar. Usa el id devuelto para dar seguimiento o reportar cualquier problema de esta solicitud al soporte de Kushki.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🔴500Server Error

curl --location '/data/v1/chargebacks/export' \ --header 'private-merchant-id: <api-key>' \ --header 'Content-Type: application/json' \ --data '{ "filters": { "time": { "request_date": { "from": "2026-01-15", "to": "2026-03-15" } } }, "webhooks": [ "https://merchant.example.com/webhooks/chargebacks" ] }'

Seguridad del webhook#

Request

Responses

Seguridad del webhook