Chargeback Management API

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

🚧
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. 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.

curl -u sk_live_xxxxxxxxxxxxxxxxxxxxxxxx: \
  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

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

📘
Ordering
Results are returned with pending chargebacks first, followed by non-pending chargebacks. There is no request sort parameter.

Example request

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 sk_live_xxxxxxxxxxxxxxxxxxxxxxxx: \
  -H "Content-Type: application/json"

Example response

{
  "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}

Returns 200 OK on success.

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

Example request

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

Example response

{
  "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": "[email protected]"
  },
  "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": "[email protected]"
    },
    "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

🚧
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

curl -X POST "https://komoju.com/api/v1/chargeback_requests/igqcsinacgl9iwz7ii3bknwpr/accept" \
  -u sk_live_xxxxxxxxxxxxxxxxxxxxxxxx: \
  -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

* = 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.

📘
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

curl -X POST "https://komoju.com/api/v1/chargeback_requests/igqcsinacgl9iwz7ii3bknwpr/defend" \
  -u sk_live_xxxxxxxxxxxxxxxxxxxxxxxx: \
  -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": "[email protected]"
    }
  }'

🚧
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. 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

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