Payment reason: disputed_by_customer

What it means

The customer disputed the collection. An indemnity claim or chargeback was raised.

Where you see it

It arrives in the webhook payload:

{
  "data": {
    "object": {
      "id": "pay_7M3X1",
      "loan_id": "loan_2K9P4",
      "status": "failed",
      "failure_code": "disputed_by_customer"
    }
  }
}

How to handle it

Pause dunning, flag for review, and reconcile once the dispute resolves.

Reconcile against live state, since webhooks are unordered and a later event may supersede this one.

In practice

Treat disputed_by_customer as one branch of your failure_code handling, not the whole story. For payments, the value tells you why a collection failed so you can respond proportionately — a technical failure needs no customer contact, whereas an insufficient-funds failure is a moment for supportive, hardship-aware messaging. Always confirm current state before acting, because a later success event (a retry that cleared) may already have superseded this failure, and webhook delivery is unordered.