Chargebacks

A chargeback occurs when a cardholder disputes a transaction directly with their bank, which in turn reverses the charge and notifies Kushki. As a merchant, you must respond within strict deadlines to protect your revenue.

This API allows you to query and export all chargeback records associated with your commerce, so you can monitor open cases, prioritize responses by urgency, and integrate chargeback data into your own systems.

Keep in mind!

Due to our risk policies, the available payment methods and the integration type may vary once you complete the affiliation. We will tell you how to proceed if this process applies to your merchant.

Chargeback Lifecycle

Every chargeback follows a defined lifecycle from the moment it is reported until it is resolved.

Chargeback Reported

The cardholder disputes a transaction with their issuing bank. The bank notifies the card network, which forwards the chargeback to Kushki.

Kushki registers the case and assigns it a chargeback_ticket_code and a request_date. The case enters the system with status INITIALIZED.

Merchant Notification

Kushki notifies you of the chargeback via email (to the addresses registered in your console). The notification_status field reflects whether this notification was sent successfully.

From this point, two deadlines start counting:

Deadline	Calculation	Purpose
`deadline_representation_date`	`request_date + 15 calendar days`	Last day to submit evidence in your defense
`deadline_resolution_date`	`request_date + 120 calendar days`	Maximum deadline for final case resolution

Representation Window

You have until deadline_representation_date to submit documentation defending the transaction. Monitor the risk_level field to prioritize which cases to act on first:

`risk_level`	Condition
`HIGH`	≤ 5 days remaining until `deadline_representation_date`
`MEDIUM`	6 – 15 days remaining
`LOW`	> 15 days remaining

Note: risk_level is calculated at query time based on the current date — it is not stored statically.

Resolution

The card network reviews the evidence and issues a final ruling. The chargeback status is updated to one of the following terminal states:

Status	Meaning
`APPROVAL`	The chargeback was resolved in your favor. The retained amount is returned.
`DECLINED`	The chargeback was resolved in the cardholder's favor. The amount is debited from your account.
`NOT_MARKABLE`	The case cannot be disputed — no representation evidence can be submitted.

Chargeback Types

Chargebacks in Ecuador are classified into two types, available in the chargeback_type field:

ADMINISTRATIVE

Disputes related to procedural or operational issues — for example, duplicate charges, processing errors, or services not rendered as agreed.

FRAUD

Disputes where the cardholder claims the transaction was unauthorized or fraudulent. These typically carry stricter deadlines and higher scrutiny.

Querying Chargebacks

The API provides two complementary methods depending on your use case:

Query — Paginated (sync)

Export — Async (webhook)

Use Query chargebacks (POST /data/v1/chargebacks/search) when you need to fetch and display chargeback data in real time — for example, in a dashboard or an automated monitoring script.

The response is synchronous and paginated. Each page returns up to 100 records.

Time filter rules:

The time object is required in every request.

Send either transaction_date or request_date — never both.

The maximum date window is 3 months.

Minimal request example:

{
  "filters": {
    "time": {
      "transaction_date": {
        "from": "2026-02-01",
        "to": "2026-02-28"
      }
    }
  },
  "pagination": {
    "page": 1,
    "page_size": 20
  }
}

Default vs. Optional Fields

Both endpoints support a fields array to request additional data beyond the default response.

Default fields (always returned)

Optional fields (request via fields[])

Field	Description
`id`	Unique identifier of the chargeback record
`chargeback_ticket_code`	Chargeback ticket number
`merchant_name`	Merchant or branch name
`chargeback_status`	Current status: `INITIALIZED`, `APPROVAL`, `DECLINED`, `NOT_MARKABLE`
`reason_code`	Reason code from the card network
`request_amount`	Amount of the original sale transaction
`currency_code`	Always `USD` for Ecuador
`transaction_date`	Date of the original sale (ISO 8601 UTC)
`request_date`	Date the chargeback was reported
`deadline_representation_date`	Calculated deadline to submit evidence (`request_date + 15 days`)
`deadline_resolution_date`	Calculated maximum resolution deadline (`request_date + 120 days`)
`risk_level`	Urgency at query time: `HIGH`, `MEDIUM`, or `LOW`

Authentication

All chargeback endpoints require your Private Merchant ID passed as a request header.

Never expose your private-merchant-id in client-side code. All calls to the Chargebacks API must be made from your backend.

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Query Chargebacks

Returns a paginated list of chargebacks matching the applied filters. Maximum 100 records per page.

Export Chargebacks

Queues an async bulk export. Kushki sends a webhook notification when the file is ready for download.

Got a suggestion on this documentation? Contact us.

Chargeback Lifecycle#

Chargeback Types#

Querying Chargebacks#

Default vs. Optional Fields#

Authentication#

Using the API#

Available Endpoints#

Chargeback Lifecycle

Chargeback Types

Querying Chargebacks

Default vs. Optional Fields

Authentication

Using the API

Available Endpoints