CHARGEBACKS
Query Chargebacks
POST /data/v1/chargebacks/searchTime filter (required)
transaction_date or request_date inside the filters.time object — not both. The maximum allowed date window is 3 months.| Option | Description |
|---|---|
transaction_date | Filter by the date of the original sale transaction |
request_date | Filter by the date the chargeback was filed |
from and to date in YYYY-MM-DD format.Optional filters
| Filter | Description |
|---|---|
chargeback_status | Filter by status — see values below |
chargeback_type | Filter by chargeback type |
chargeback_ticket_code | Filter by chargeback ticket number |
country_name | Filter by merchant country |
card_country_name | Filter by the country of the card used in the transaction |
Chargeback statuses
| Value | Meaning |
|---|---|
INITIALIZED | Chargeback received and under review |
APPROVAL | Chargeback resolved in the cardholder's favor |
DECLINED | Chargeback resolved in the merchant's favor |
NOT_MARKABLE | Chargeback cannot be contested |
Pagination
| Field | Required | Description |
|---|---|---|
pagination.page | ✅ | Page number to retrieve, starting at 1 |
pagination.page_size | ✅ | Records per page — max 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 |
merchant_name | Merchant name |
chargeback_status | Current status |
reason_code | Card network reason code (e.g. 4834, 4853) |
request_amount | Disputed amount |
currency_code | Always COP for Colombia |
transaction_date | Date of the original sale |
request_date | Date the chargeback was filed |
deadline_representation_date | Deadline to submit representment documentation |
deadline_resolution_date | Expected resolution date |
risk_level | Risk level assigned to the chargeback: LOW, MEDIUM, HIGH |
Export Chargebacks
POST /data/v1/chargebacks/exportfilters 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 the webhooks array with the download link and its expiration timestamp.{
"id": "1339b164-9298-4ea1-a52a-a9c053879194"
}webhooks field
| Field | Required | Description |
|---|---|---|
webhooks | ✅ | Array of callback URLs — max 5 URLs |
expiration_timestamp. The link is valid for 4 hours from generation.Webhook security
| Header | Description |
|---|---|
X-Kushki-Id | Unix timestamp in 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.Example Request — Query
{
"filters": {
"time": {
"transaction_date": {
"from": "2026-01-01",
"to": "2026-03-31"
}
},
"chargeback_status": ["INITIALIZED"]
},
"pagination": {
"page": 1,
"page_size": 20
}
}Authentication
Using the API
🟢 Production
🧪 Sandbox (UAT)
https://api.kushkipagos.com/Available Endpoints
Got a suggestion on this documentation? Contact us.
Modified at 2026-07-11 00:04:33