The Chargebacks API lets you query and export chargeback records for your merchant account in Chile 🇨🇱 — directly via API, without logging into the Kushki Console.Two operations are available:| Operation | Endpoint | Description |
|---|
| Search | POST /data/v1/chargebacks/search | Paginated list of chargebacks with filters |
| Export | POST /data/v1/chargebacks/export | Async export — Kushki POSTs the download link to your webhook when ready |
Search chargebacks#
Returns a paginated list of chargebacks matching your filters.Minimal request — by transaction date#
{
"filters": {
"time": {
"transaction_date": {
"from": "2026-02-01",
"to": "2026-02-28"
}
}
},
"pagination": {
"page": 1,
"page_size": 20
}
}
Request with filters and additional fields#
{
"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
}
}
Filters reference#
Time filter (required)#
Use either transaction_date (the original payment date) or request_date (the date the chargeback was raised) — not both.| Field | Description |
|---|
time.transaction_date.from / to | Filter by original transaction date (YYYY-MM-DD) |
time.request_date.from / to | Filter by chargeback request date (YYYY-MM-DD) |
Optional filters#
| Filter | Type | Description |
|---|
chargeback_status | array | One or more status values — see table below |
chargeback_type | array | Type of chargeback |
ticket_code | array | Kushki ticket code of the original transaction |
chargeback_ticket_code | array | Chargeback-specific ticket code |
country_name | array | ["CHILE"] |
Chargeback status values#
| Status | Description |
|---|
INITIALIZED | Chargeback created — pending review |
APPROVAL | Chargeback resolved in favor of the merchant |
DECLINED | Chargeback resolved in favor of the cardholder |
NOT_MARKABLE | Chargeback cannot be actioned or disputed |
Additional fields#
By default, the search response includes a standard set of fields. Use the fields array to request additional data:| Field | Description |
|---|
ticket_code | Ticket code of the original transaction |
chargeback_ticket_code | Chargeback-specific ticket code |
business_unit | Business unit associated with the merchant |
chargeback_type | Type of chargeback raised |
Export chargebacks#
Initiates an asynchronous export of chargeback records. The request body follows the same structure as POST /data/v1/chargebacks/search, with the addition of the webhooks field. Kushki processes the export in the background and sends a POST notification to each URL in the webhooks array when the file is ready — including the download link and its expiration timestamp.Basic export#
{
"filters": {
"time": {
"request_date": {
"from": "2026-01-15",
"to": "2026-03-15"
}
}
},
"webhooks": [
"https://yoursite.com/webhooks/chargebacks"
]
}
{
"id": "1339b164-9298-4ea1-a52a-a9c053879194"
}
id to track the request or report any delivery issues to Kushki support. When the file is ready, Kushki POSTs the following payload to each configured webhook URL:{
"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
}
file_url is an S3 pre-signed URL valid for 4 hours from the moment of generation. Check expiration_timestamp (Unix timestamp, milliseconds) before attempting the download.
Export with filters and additional fields#
{
"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"
]
}
The export endpoint returns immediately with an id. The actual file is generated asynchronously — your webhook receives the download link when it's ready. webhooks accepts a maximum of 5 URLs. Design your webhook handler to be idempotent in case of delivery retries.
Webhook security#
To verify that a notification was sent by Kushki and not a third party, validate the following headers included in every webhook call:| Header | Description |
|---|
X-Kushki-Id | Unix timestamp (13 digits, milliseconds) of when the notification was sent. |
X-Kushki-Signature | HMAC SHA256 signature of private-merchant-id|request|X-Kushki-Id. The signing secret is the merchant's own private-merchant-id. |
To validate the signature on your side, compute:HMAC-SHA256({private-merchant-id}, "{private-merchant-id}|{request}|{X-Kushki-Id}")
X-Kushki-Signature. If they match, the notification is authentic.
Authentication#
Using the API#
https://api.kushkipagos.com/
Available Endpoints#
Query Chargebacks
Paginated search with filters by date, status, type, and ticket code.
Request Chargeback Export
Async export — returns immediately with a job ID. Download link delivered to your webhook URL.
Got a suggestion on this documentation? Contact us.
