Disputes
The disputes endpoints of the Kashu API, with their parameters, objects, errors and examples. The guide explains how they fit together.
The dispute object
| Field | Type | About |
|---|
id | string | An id that starts dp_. |
object | string | Always "dispute". |
payment | string | An id that starts py_. |
amount | integer or null | In the currency's minor unit, such as cents for USD. More than 0. |
currency | string | Three capital letters, such as USD. |
status | enum | One of warning_needs_response, warning_under_review, warning_closed, needs_response, under_review, won, lost. |
reason | enum | One of bank_cannot_process, credit_not_processed, customer_initiated, debit_not_authorized, duplicate, fraudulent, general, incorrect_account_details, insufficient_funds, product_not_received, product_unacceptable, subscription_canceled, unrecognized. |
evidence_due_by | integer or null | Unix seconds. |
livemode | boolean | |
created | integer | Unix seconds. |
{
"id": "dp_1a2B3c4D5e6F7g8H9i0J1k2L",
"object": "dispute",
"payment": "py_1a2B3c4D5e6F7g8H9i0J1k2L",
"amount": 4999,
"currency": "USD",
"status": "needs_response",
"reason": "product_not_received",
"evidence_due_by": 1762473600,
"livemode": false,
"created": 1762473600
}
GET /v1/disputes/{id}
Retrieve a dispute.
- Scope
disputes:read- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Not used. A read changes nothing.
Parameters
| Name | In | Type | Required | About |
|---|
id | path | string | Required | An id that starts dp_. |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Errors
Examples
curl https://api.kashupay.com/v1/disputes/dp_1a2B3c4D5e6F7g8H9i0J1k2L \
-H "Authorization: Bearer $KASHU_SECRET_KEY"
const dispute = await kashu("GET", "/v1/disputes/dp_1a2B3c4D5e6F7g8H9i0J1k2L");
console.log(dispute.status);
GET /v1/disputes
List disputes, newest first.
- Scope
disputes:read- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Not used. A read changes nothing.
Parameters
| Name | In | Type | Required | About |
|---|
payment | query | string | Optional | An id that starts py_. |
limit | query | integer | Optional | At least 1. Up to 100. Defaults to 10. |
cursor | query | string | Optional | |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Errors
Examples
curl "https://api.kashupay.com/v1/disputes?limit=3" \
-H "Authorization: Bearer $KASHU_SECRET_KEY"
const list = await kashu("GET", "/v1/disputes?limit=3");
console.log(list.has_more);
POST /v1/disputes/{id}/evidence
Send evidence for a dispute. Not available yet: every request answers feature_unavailable.
- Scope
disputes:write- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Required. This endpoint moves money. See Idempotency.
Parameters
| Name | In | Type | Required | About |
|---|
id | path | string | Required | An id that starts dp_. |
Idempotency-Key | header | string | Required | Required. Retry with the same key and get the same result. Up to 255 characters. |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Request body
| Field | Type | Required | About |
|---|
evidence | map of strings | Optional | Keys up to 40 characters, values up to 20000. |
Errors
| Status | Codes |
|---|
| 400 | invalid_json, parameter_missing, parameter_invalid, parameter_unknown, api_version_invalid, idempotency_key_missing, idempotency_key_invalid, idempotency_key_reused |
| 401 | api_key_missing, api_key_invalid, api_key_expired |
| 403 | livemode_unavailable, insufficient_scope, publishable_key_not_allowed, feature_unavailable |
| 404 | resource_missing |
| 409 | idempotency_key_in_use |
| 429 | rate_limited |
| 500 | api_error |
Examples
curl https://api.kashupay.com/v1/disputes/dp_1a2B3c4D5e6F7g8H9i0J1k2L/evidence \
-X POST \
-H "Authorization: Bearer $KASHU_SECRET_KEY" \
-H "Idempotency-Key: disputes-submit-evidence-1001"
const dispute = await kashu("POST", "/v1/disputes/dp_1a2B3c4D5e6F7g8H9i0J1k2L/evidence", undefined, { idempotencyKey: "disputes-submit-evidence-1001" });
console.log(dispute.status);
POST /v1/disputes/{id}/accept
Accept a dispute and give up the disputed amount. Not available yet: every request answers feature_unavailable.
- Scope
disputes:write- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Required. This endpoint moves money. See Idempotency.
Parameters
| Name | In | Type | Required | About |
|---|
id | path | string | Required | An id that starts dp_. |
Idempotency-Key | header | string | Required | Required. Retry with the same key and get the same result. Up to 255 characters. |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Request body
Send no body, or an empty JSON object.
Errors
| Status | Codes |
|---|
| 400 | invalid_json, parameter_unknown, api_version_invalid, idempotency_key_missing, idempotency_key_invalid, idempotency_key_reused |
| 401 | api_key_missing, api_key_invalid, api_key_expired |
| 403 | livemode_unavailable, insufficient_scope, publishable_key_not_allowed, feature_unavailable |
| 404 | resource_missing |
| 409 | idempotency_key_in_use |
| 429 | rate_limited |
| 500 | api_error |
Examples
curl https://api.kashupay.com/v1/disputes/dp_1a2B3c4D5e6F7g8H9i0J1k2L/accept \
-X POST \
-H "Authorization: Bearer $KASHU_SECRET_KEY" \
-H "Idempotency-Key: disputes-accept-1001"
const dispute = await kashu("POST", "/v1/disputes/dp_1a2B3c4D5e6F7g8H9i0J1k2L/accept", undefined, { idempotencyKey: "disputes-accept-1001" });
console.log(dispute.status);