Disputes

A Dispute is a chargeback raised by a cardholder. The Python SDK exposes the read endpoints, the tag-only update, the lifecycle actions (accept, submit), plus evidence upload + listing.

Namespace: client.disputes.

Methods

`retrieve`

dispute = client.disputes.retrieve("dp_123")

`list`

disputes = client.disputes.list(limit=50, offset=0)

Returns list[Dispute].

`update`

dispute = client.disputes.update(
    "dp_123",
    tags={"reviewed_by": "ops@example.com"},
)

Only tags is mutable from the API.

`accept`

result = client.disputes.accept(
    "dp_123",
    idempotency_key="dispute-accept-dp_123",
)

Concedes the dispute. Returns the raw data payload — shape varies by processor.

`submit`

client.disputes.submit("dp_123", idempotency_key="dispute-submit-dp_123")

Submits previously-uploaded evidence for review. Call once you've finished upload_evidence(...) for every supporting document.

`upload_evidence`

with open("receipt.pdf", "rb") as f:
    client.disputes.upload_evidence(
        "dp_123",
        file=f,
        filename="receipt.pdf",
        content_type="application/pdf",
        idempotency_key="dispute-evidence-receipt",
    )

Multipart upload. The API accepts JPEG / PNG / PDF up to 1 MB per file. Call once per file, then call submit(...) to finalize.

`list_evidence`

files = client.disputes.list_evidence("dp_123")

Returns the raw data payload (list of evidence file objects).

Object shape

Dispute follows the canonical API shape. The common fields:

Field	Notes
`id`	Always present.
`state`	`"NEEDS_RESPONSE"`, `"PENDING"`, `"WON"`, `"LOST"`.
`amount`	Integer in the smallest currency unit.
`currency`	Three-letter ISO.
`transfer_id`	The disputed transfer.
`due_at`	Deadline for evidence submission.
`tags`	Free-form metadata; mutable via `update`.
`created_at`, `updated_at`	Standard.

Examples

React to a `dispute.created` webhook

if event.type == "dispute.created":
    dispute = event.data
    notify_ops(dispute["id"], dispute.get("amount"), dispute.get("due_at"))

Build, upload, and submit evidence

for path, mime in [
    ("receipt.pdf",   "application/pdf"),
    ("delivery.jpg",  "image/jpeg"),
    ("emails.pdf",    "application/pdf"),
]:
    with open(path, "rb") as f:
        client.disputes.upload_evidence(
            "dp_123",
            file=f,
            filename=path,
            content_type=mime,
            idempotency_key=f"evidence-{path}",
        )

client.disputes.submit("dp_123", idempotency_key="submit-dp_123-1")

Concede when the cost of contesting outweighs the chargeback

client.disputes.accept("dp_123", idempotency_key="accept-dp_123-1")

Disputes

On this page