Chargebacks
| 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
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)
transaction_date or request_date inside filters.time — not both. The maximum allowed date window is 3 months.| Field | Description |
|---|---|
time.transaction_date.from / to | Filter by the date of the original sale transaction (YYYY-MM-DD) |
time.request_date.from / to | Filter by the date the chargeback was filed (YYYY-MM-DD) |
Optional filters
| Filter | Type | Description |
|---|---|---|
chargeback_status | array | One or more status values — see table below |
chargeback_type | array | ADMINISTRATIVE or FRAUD |
chargeback_ticket_code | string | Chargeback-specific ticket number |
country_name | array | Merchant country. For Mexico: ["MEXICO"] |
card_country_name | array | Country of the card used in the transaction |
Chargeback status values
| Status | Description |
|---|---|
INITIALIZED | Chargeback received — pending review |
APPROVAL | Chargeback resolved in the cardholder's favor |
DECLINED | Chargeback resolved in the merchant's favor |
NOT_MARKABLE | Chargeback cannot be contested |
Pagination (required)
| Field | Description |
|---|---|
pagination.page | Page number, starting at 1 |
pagination.page_size | Records per page — maximum 100 |
total and total_pages for full pagination.Additional fields
fields array to request additional ones: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, sourceDefault response fields
| Field | Description |
|---|---|
id | Unique chargeback record ID |
chargeback_ticket_code | Chargeback ticket number. May be NO_INFO when unavailable |
merchant_name | Merchant or branch name associated with the transaction |
chargeback_status | Current status — see table above |
reason_code | Card network reason code (e.g. 4834, 4853) |
request_amount | Amount disputed in the original sale transaction |
currency_code | ISO 4217 currency code. For Mexico: MXN |
transaction_date | Date and time of the original sale (ISO 8601 UTC) |
request_date | Date the chargeback was reported to the card network or processor |
deadline_representation_date | Calculated. request_date + 15 calendar days |
deadline_resolution_date | Calculated. request_date + 120 calendar days |
risk_level | Calculated. HIGH (≤5 days to deadline), MEDIUM (6–15 days), or LOW (>15 days) |
Export chargebacks
filters and fields as the search endpoint, plus a webhooks array.How it works
1.
200 OK with a unique id.2.
3.
POST notification to each URL in webhooks with 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
}4-hour download window
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.| Field | Required | Description |
|---|---|---|
webhooks | Yes | Array of callback URLs — maximum 5 |
Async export
webhooks accepts a maximum of 5 URLs. Design your webhook handler to be idempotent in case of delivery retries.Webhook security
| Header | Description |
|---|---|
X-Kushki-Id | Unix timestamp (milliseconds) of when the notification was sent |
X-Kushki-Signature | HMAC-SHA256 signature of {private-merchant-id}|{request}|{X-Kushki-Id} |
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
🟢 Production
🧪 Sandbox (UAT)
https://api.kushkipagos.com/Available Endpoints
Got a suggestion on this documentation? Contact us.
Modified at 2026-08-03 19:29:01