---
title: "Chargeback Management API"
description: "Learn how to use the Chargeback Management API to programmatically retrieve, manage, accept, and defend chargebacks and disputes."
url: "https://docs.priv.staging.komoju-dev.tools/en/docs/development/chargeback-management-api"
source_url: "https://docs.priv.staging.komoju-dev.tools/en/docs/development/chargeback-management-api.md"
language: en
last_modified: "2026-06-25"
---

The Chargeback Management API lets merchants programmatically **retrieve, manage, and respond to chargebacks**. It replaces manual workflows (email or the chargeback portal) so you can integrate chargeback handling directly into your own internal systems.

This guide covers the merchant API endpoints for chargeback requests:

- `GET /api/v1/chargeback_requests` — list chargeback requests
- `GET /api/v1/chargeback_requests/{id}` — get a chargeback request's details
- `POST /api/v1/chargeback_requests/{id}/accept` — accept a chargeback
- `POST /api/v1/chargeback_requests/{id}/defend` — defend a chargeback

> ⚠️ **Warning:** **Feature gate**
>
> All chargeback endpoints are guarded by chargeback feature enablement for your merchant account. If the feature is not enabled, these endpoints return `404 Not Found`. Contact KOMOJU support to enable it.

# Authentication

Use your merchant secret key with [Authentication](https://docs.priv.staging.komoju-dev.tools/en/docs/introduction/authentication.md). Send the secret key as the HTTP Basic Auth username and leave the password blank. You can find your secret key on the API key page of your merchant dashboard.

```shell
curl -u YOUR_SECRET_KEY: \
  https://komoju.com/api/v1/chargeback_requests

```

# Common behavior

- Date/time inputs must be ISO 8601 `date-time` strings (for example `2026-05-01T00:00:00Z`).
- List endpoints use the standard pagination format: `resource`, `total`, `page`, `per_page`, `last_page`, `data`.
- `per_page` defaults to `10`, with a maximum of `100`.

## Chargeback statuses

| Status | Description |
| --- | --- |
| `pending` | Awaiting your response (accept or defend). |
| `accepted` | You accepted the chargeback. |
| `defended` | You submitted a defense. |
| `cancelled` | The chargeback was cancelled. |
| `expired` | The response window passed without a response. |
| `lost` | The chargeback was decided against you. |

# List chargeback requests

Retrieves a paginated list of chargeback requests for the authenticated merchant.

| Authentication | Method | Endpoint |
| --- | --- | --- |
| Secret key | GET | [https://komoju.com/api/v1/chargeback_requests](https://komoju.com/api/v1/chargeback_requests) |

Returns `200 OK` on success.

| Query Parameter | Type | Description |
| --- | --- | --- |
| `status` | string | Filter by status. One of `pending`, `accepted`, `cancelled`, `expired`, `defended`, `lost`. |
| `payment_id` | string | Filter by the associated payment ID. |
| `start_time` | string date-time | Lower bound (inclusive) on the chargeback's created time. |
| `end_time` | string date-time | Upper bound (inclusive) on the chargeback's created time. |
| `due_date_start` | string date-time | Lower bound (inclusive) on the chargeback's due date. |
| `due_date_end` | string date-time | Upper bound (inclusive) on the chargeback's due date. |
| `per_page` | integer | Results per page. Defaults to `10`, max `100`. |
| `page` | integer | Page number. Defaults to `1`. |

> ℹ️ **Note:** **Ordering**
>
> Results are returned with `pending` chargebacks first, followed by non-pending chargebacks. There is no request sort parameter.

## Example request

```shell
curl -X GET "https://komoju.com/api/v1/chargeback_requests?status=pending&start_time=2026-05-01T00:00:00Z&end_time=2026-05-31T23:59:59Z&per_page=10&page=1" \
  -u YOUR_SECRET_KEY: \
  -H "Content-Type: application/json"

```

## Example response

```json
{
  "resource": "list",
  "total": 2,
  "page": 1,
  "per_page": 10,
  "last_page": 1,
  "data": [
    {
      "id": "igqcsinacgl9iwz7ii3bknwpr",
      "payment_id": "enj2pugqquwjlb1slvk3pikr8",
      "amount": 1000,
      "currency": "JPY",
      "payment_method": {
        "type": "credit_card",
        "brand": "visa",
        "last_four_digits": "4242"
      },
      "reason_code": "CB_Fraud",
      "reason": "Fraud",
      "created_at": "2026-05-06T02:49:18Z",
      "due_date": "2026-05-22T02:49:18Z",
      "status": "pending"
    }
  ]
}

```

# Get a chargeback request

Retrieves the details of a single chargeback request, including its timeline, payment, customer, and defense (if one exists).

| Authentication | Method | Endpoint |
| --- | --- | --- |
| Secret key | GET | [https://komoju.com/api/v1/chargeback_requests/{id}](https://komoju.com/api/v1/chargeback_requests/%7Bid%7D) |

Returns `200 OK` on success.

| Path Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | The chargeback request UUID. |

## Example request

```shell
curl -X GET "https://komoju.com/api/v1/chargeback_requests/igqcsinacgl9iwz7ii3bknwpr" \
  -u YOUR_SECRET_KEY: \
  -H "Content-Type: application/json"

```

## Example response

```json
{
  "id": "2sqtcy1hpq0y3f3sos0l1zrww",
  "status": "defended",
  "reason_code": "CB_Fraud",
  "reason": "Fraud / Unauthorized Transaction",
  "created_at": "2026-05-28T04:21:21Z",
  "due_date": "2026-06-07T14:59:59Z",
  "last_updated_at": "2026-05-28T04:59:18Z",
  "timeline": [
    {
      "type": "created",
      "occurred_at": "2026-05-28T04:21:21Z"
    },
    {
      "type": "defended",
      "occurred_at": "2026-05-28T04:59:18Z"
    },
    {
      "type": "response_due",
      "occurred_at": "2026-06-07T14:59:59Z"
    }
  ],
  "payment": {
    "id": "7zk4ecpe4xbzzoyhyzd5hszus",
    "amount": 1864,
    "currency": "JPY",
    "created_at": "2026-04-23T02:18:57Z",
    "captured_at": "2026-04-23T02:18:57Z",
    "payment_method": {
      "type": "web_money",
      "brand": null,
      "last_four_digits": null
    },
    "masked_card_number": null
  },
  "customer": {
    "name": "freeman gordon",
    "email": "gordon@example.com"
  },
  "defense": {
    "product_name": "Premium Plan",
    "reason": "Customer received the product as agreed.",
    "shipping_info": {
      "company_name": "DHL",
      "shipping_date": "2026-05-20",
      "tracking_number": "TRACK-12345",
      "shipping_address": "1-2-3 Tokyo"
    },
    "recipient_info": {
      "name": "Jane Doe",
      "phone": "090-1234-5678",
      "email": "jane@example.com"
    },
    "documents": [
      {
        "file_name": "evidence.pdf",
        "content_type": "application/pdf",
        "file_size": 63,
        "uploaded_at": "2026-05-28T04:59:18Z",
        "url": "https://example-uploads.s3.ap-northeast-1.amazonaws.com/chargeback_defense/...pdf"
      }
    ]
  }
}

```

When a defense exists, the `defense` object contains:

| Attribute | Description |
| --- | --- |
| `product_name` | Name of the product or service. |
| `reason` | The merchant's defense reason. |
| `shipping_info` | `company_name`, `shipping_date`, `tracking_number`, `shipping_address`. |
| `recipient_info` | `name`, `phone`, `email`. |
| `documents` | Array of `file_name`, `content_type`, `file_size`, `uploaded_at`, `url`. |

# Accept a chargeback request

Accepts a chargeback, agreeing to the dispute. This endpoint takes no request body and returns `204 No Content` (empty body) on success.

| Authentication | Method | Endpoint |
| --- | --- | --- |
| Secret key | POST | [https://komoju.com/api/v1/chargeback_requests/{id}/accept](https://komoju.com/api/v1/chargeback_requests/%7Bid%7D/accept) |

> ⚠️ **Warning:** **Rules**
>
> - You can only accept a chargeback while its status is `pending`.
- If the due date has passed, the request returns an error.
- Accepting an already-accepted chargeback returns `204` (idempotent).

## Example request

```shell
curl -X POST "https://komoju.com/api/v1/chargeback_requests/igqcsinacgl9iwz7ii3bknwpr/accept" \
  -u YOUR_SECRET_KEY: \
  -H "Content-Type: application/json"

```

# Defend a chargeback request

Submits a defense against a chargeback, including supporting documentation. Returns `204 No Content` (empty body) on success.

| Authentication | Method | Endpoint |
| --- | --- | --- |
| Secret key | POST | [https://komoju.com/api/v1/chargeback_requests/{id}/defend](https://komoju.com/api/v1/chargeback_requests/%7Bid%7D/defend) |

* = required

| Request Attribute | Type | Description |
| --- | --- | --- |
| `description` * | string | Explanation of your defense. |
| `document` * | object | Supporting document. See below. |
| `product_name` | string | Name of the product or service. |
| `shipping_info` | object | `company_name`, `shipping_date` (e.g. `2026-05-20`), `tracking_number`, `shipping_address`. |
| `recipient_info` | object | `name`, `phone`, `email`. |

The `document` object:

| Request Attribute | Type | Description |
| --- | --- | --- |
| `document_base64` * | string | Base64-encoded file contents. |
| `filename` | string | Original file name. |
| `content_type` | string | MIME type of the file. |

> ℹ️ **Note:** **Document requirements**
>
> - The base64 payload must be **15 MB or less**.
- Supported types: **PDF, JPG/JPEG, PNG, GIF**.
- The file type is inferred from the file's bytes, not the filename. Other types are rejected with a validation error.

## Example request

```shell
curl -X POST "https://komoju.com/api/v1/chargeback_requests/igqcsinacgl9iwz7ii3bknwpr/defend" \
  -u YOUR_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Premium Plan",
    "description": "Customer received the product as agreed.",
    "document": {
      "document_base64": "JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCiUlRU9G",
      "filename": "evidence.pdf",
      "content_type": "application/pdf"
    },
    "shipping_info": {
      "company_name": "DHL",
      "shipping_date": "2026-05-20",
      "tracking_number": "TRACK-12345",
      "shipping_address": "1-2-3 Tokyo"
    },
    "recipient_info": {
      "name": "Jane Doe",
      "phone": "090-1234-5678",
      "email": "jane@example.com"
    }
  }'

```

> ⚠️ **Warning:** **Rules**
>
> - You can only defend a chargeback while its status is `pending`.
- If the due date has passed, the request returns an error.
- Defending an already-defended chargeback returns `204` (idempotent).
- Duplicate defenses are prevented; only one defense can be created per chargeback request.

# Errors

Chargeback endpoints return [standard API error objects](https://docs.priv.staging.komoju-dev.tools/en/docs/introduction/errors.md). Common cases:

| Status | When |
| --- | --- |
| `401 Unauthorized` | The secret key is missing or invalid. |
| `404 Not Found` | The feature is disabled for your merchant, or the chargeback ID does not exist for the authenticated merchant. |
| `400 Bad Request` | `Only pending chargebacks can be accepted.` / `Only pending chargebacks can be defended.` / `Chargeback due date has passed and can no longer be responded to.` / invalid or oversized base64 document payload. |
| `422 Unprocessable Entity` | Missing required defend parameters (for example `description` or `document`), or invalid date-time format in query params. |

## Error body shape

```json
{
  "error": {
    "code": "bad_request",
    "message": "Only pending chargebacks can be defended.",
    "param": null,
    "details": {}
  }
}

```