Chargebacks

The Chargebacks API lets you query and export chargeback records for your merchant account in Peru 🇵🇪 — directly via API, without logging into the Kushki Console. This is the same Chargebacks service available under Online Payments, exposed here for merchants integrating Card Present only.

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": ["PERU"]
  },
  "fields": [
    "ticket_code",
    "business_unit",
    "chargeback_type"
  ],
  "pagination": {
    "page": 1,
    "page_size": 20
  }
}

Filters reference

Time filter (required)

Send either 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 Peru: `["PERU"]`
`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

The response includes total and total_pages for full pagination.

Additional fields

By default, the response includes a standard set of fields per chargeback. Use the 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, source

Default 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 Peru: `PEN`
`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

Initiates an asynchronous export of chargeback records. The request accepts the same filters and fields as the search endpoint, plus a webhooks array.

How it works

Send the request — you immediately receive a 200 OK with a unique id.

Kushki generates the file in the background.

Once ready, Kushki sends a 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"
  ]
}

Response:

{
  "id": "1339b164-9298-4ea1-a52a-a9c053879194"
}

Use the 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

Validate these headers on every notification to confirm it came from Kushki:

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}`

To validate on your side, compute:

HMAC-SHA256({private-merchant-id}, "{private-merchant-id}|{request}|{X-Kushki-Id}")

Compare the result with X-Kushki-Signature. If they match, the notification is authentic.

Authentication

Using the API

🟢 Production

🧪 Sandbox (UAT)

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.

Search chargebacks#

Minimal request — by transaction date#

Request with filters and additional fields#

Filters reference#

Time filter (required)#

Optional filters#

Chargeback status values#

Pagination (required)#

Additional fields#

Default response fields#

Export chargebacks#

How it works#

Basic export#

Webhook security#

Authentication#

Using the API#

Available Endpoints#

Search chargebacks

Minimal request — by transaction date

Request with filters and additional fields

Filters reference

Time filter (required)

Optional filters

Chargeback status values

Pagination (required)

Additional fields

Default response fields

Export chargebacks

How it works

Basic export

Webhook security

Authentication

Using the API

Available Endpoints