Disputes

A dispute is a buyer asking their bank to reverse a payment. Kashu records each dispute against its payment, so you can see it, follow it and act on it in your own systems.

Find disputes

GET /v1/disputes lists disputes, newest first. Add payment to find the dispute on one payment. GET /v1/disputes/{id} reads one:

curl https://api.kashupay.com/v1/disputes/dp_... \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

{
  "id": "dp_...",
  "object": "dispute",
  "payment": "py_...",
  "amount": 4999,
  "currency": "USD",
  "status": "needs_response",
  "reason": "product_not_received",
  "evidence_due_by": 1762473600,
  "livemode": false,
  "created": 1762473600
}

A payment has at most one dispute. A later dispute of the same payment moves the same record.

Read a dispute

status is where the dispute stands. needs_response and under_review are open, won and lost are closed. The three warning_ statuses are the same stages for a warning that has not become a dispute.
reason is the buyer's reason, such as fraudulent or product_not_received. general covers the reasons that fit no other word.
evidence_due_by is when evidence must reach the card network, in Unix seconds, or null.
amount is null when the card network has not stated one yet.

A dispute never changes the payment's amounts. The payment shows disputed true.

Follow disputes by webhook

dispute.created arrives when a dispute is recorded, and dispute.updated each time it moves. Webhooks explains how to receive them.

What is not available yet

Answering a dispute. POST /v1/disputes/{id}/evidence and POST /v1/disputes/{id}/accept exist so your code can call them, but both answer 403 feature_unavailable today.
Making a dispute in test mode. Test mode has no way to dispute a payment yet.

For help with a dispute on a live payment, write to help@kashupay.com.