The Chargebacks API lets you query and export chargeback records for your merchant account in Mexico 🇲🇽 — 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": ["MEXICO"]
},
"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 | ["MEXICO"] |
Chargeback status values#
| Status | Description |
|---|
INITIALIZED | Chargeback created — pending review |
IN_PROCESS | Under review by the bank or network |
WON | Dispute resolved in favor of the merchant |
LOST | Dispute resolved in favor of the cardholder |
CANCELLED | Chargeback cancelled |
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. 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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
{
"exportId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "https://storage.kushkipagos.com/exports/chargebacks-2026-05-29.csv",
"expiresAt": "2026-05-30T12:00:00Z"
}
The export endpoint returns immediately with an id. The actual file is generated asynchronously — your webhook receives the download link when it's ready. Design your webhook handler to be idempotent in case of delivery retries.
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.
