disputes

A dispute (a chargeback, or an inquiry that may become one) is kept as the provider last reported it: outcome is open while it is undecided (for a chargeback the provider has taken the money back until it decides), won when it ended in your favour or never became a chargeback, lost when the cardholder won. Each step is also sent as the payment.disputed webhook event. A dispute of a payment Payrudder did not make has no invoice_id. Stripe's and Paddle's own words are in provider_status; UNVERIFIED against a live account. 503 when the payment service does not answer.

{
  "disputes": [
    {
      "id": "string",
      "provider": "stripe",
      "dispute_id": "string",
      "payment_ref": "string",
      "amount_minor": "string",
      "currency": "string",
      "outcome": "open",
      "formal": false,
      "provider_status": "string",
      "opened_time": "2026-11-03T10:15:00Z",
      "handled": false,
      "note_count": 1
    }
  ]
}

curl -X GET https://YOUR-API-ADDRESS/v1/disputes \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

What you did with the case inside Payrudder: each note, and each time it was marked as handled or the mark was lifted. id is the case's id as GET /v1/disputes gives it. actor (who) is left out for a viewer of the account, as in the audit log. At most the newest 200. 404 payments.dispute.not_found for a case that is not yours.

{
  "events": [
    {
      "id": "string",
      "action": "note",
      "create_time": "2026-11-03T10:15:00Z"
    }
  ]
}

curl -X GET https://YOUR-API-ADDRESS/v1/disputes/<id>/history \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

A note is for you and your colleagues: what you found out, what you answered at the provider, where the evidence is. It is kept with the case, one to 2000 characters, and recorded in the audit log without its text. Payrudder sends it nowhere: the case is answered at the provider, Payrudder submits no evidence.

{
  "note": "string"
}

{
  "id": "string",
  "action": "note",
  "create_time": "2026-11-03T10:15:00Z"
}

curl -X POST https://YOUR-API-ADDRESS/v1/disputes/<id>/notes \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note":"string"}'

Your own mark: it says you have dealt with the case (answered it at the provider, accepted it, refunded it). It changes nothing at the provider, in the payment ledger, or in what was announced (payment.disputed). Setting what is already set is not an error and writes nothing. Recorded in the audit log. The answer is the case as it stands.

{
  "handled": false
}

{
  "id": "string",
  "provider": "stripe",
  "dispute_id": "string",
  "payment_ref": "string",
  "amount_minor": "string",
  "currency": "string",
  "outcome": "open",
  "formal": false,
  "provider_status": "string",
  "opened_time": "2026-11-03T10:15:00Z",
  "handled": false,
  "note_count": 1
}

curl -X PUT https://YOUR-API-ADDRESS/v1/disputes/<id>/handled \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handled":false}'