Handle disputes

When a cardholder asks their bank to reverse a card payment, the bank opens a case against your sale. Fluveo records that case as a Dispute (du_...), takes the disputed amount out of your balance while it runs, and tells your webhook endpoint about every step. From there you have two moves: prove the sale was good, and let the bank rule; or accept the case, and the amount stays with the buyer.

Only card payments can be disputed. Every store reads, answers and closes its disputes with the same /v1/disputes calls shown on this page.

From the bank's case to the final ruling#

1. The case opens. A Dispute appears on the charge and charge.dispute.created reaches your endpoint.
2. When the amount comes out of your balance, charge.dispute.funds_withdrawn follows.
3. A new chargeback has status needs_response. A question the bank asks before any chargeback (an inquiry) has warning_needs_response. Either way, evidence_details.due_by holds your deadline as a Unix timestamp.
4. Before that deadline, submit evidence or close the dispute to accept it. Submitted evidence moves the dispute to under_review and sends charge.dispute.updated.
5. The ruling arrives as charge.dispute.closed, with status set to won or lost (warning_closed when an inquiry ends). A win that returns the money also sends charge.dispute.funds_reinstated.

Losing a dispute can push your balance below zero. Payouts then wait until new sales cover the gap; see Balance and payouts.

Dispute statuses#

Events#

In every one of these events, data.object is the full Dispute, the same object GET /v1/disputes/{id} returns.

Find your disputes#

GET /v1/disputes pages through your disputes with the newest first. To see only one payment's disputes, add payment_intent or charge.

curl -G https://api.fluveo.com/v1/disputes \
  -H "Authorization: Bearer sk_test_..." \
  -d limit=10

const response = await fetch("https://api.fluveo.com/v1/disputes?limit=10", {
  headers: { Authorization: "Bearer sk_test_..." },
});
const { data, has_more } = await response.json();

import requests

disputes = requests.get(
    "https://api.fluveo.com/v1/disputes",
    headers={"Authorization": "Bearer sk_test_..."},
    params={"limit": 10},
).json()

<?php
$ch = curl_init("https://api.fluveo.com/v1/disputes?limit=10");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."],
]);
$disputes = json_decode(curl_exec($ch), true);

To read a single dispute, call GET /v1/disputes/{id}. Add expand[]=charge or expand[]=payment_intent to get its Charge or its PaymentIntent in the same answer; on a list, write expand[]=data.charge. Every field of the Dispute is in the API reference.

Send evidence#

Your evidence should show the order was real and reached the buyer: the order receipt, the tracking number, the messages you exchanged. Facts you can type go in the text fields of evidence. A document goes in a file field, named by the file_ id it got when you uploaded it. You can save the evidence as a draft as many times as you need, then submit it once.

A new dispute already holds some evidence, copied from the payment when the dispute opened: the buyer's email address, name and address (billing_address), the shipping address and the payment's description. evidence_details.has_evidence stays false until you write. Read the dispute before you post: the keys you send replace those values (an empty value clears one), and the keys you leave out stay. The first events, charge.dispute.created and charge.dispute.funds_withdrawn, show those keys empty; GET /v1/disputes/{id} shows them filled.

1. Upload your evidence files#

   Send each document to POST /v1/files with purpose=dispute_evidence (the API reference lists the file fields). Note the file_ id in the answer: an evidence[...] file field takes it in the next step.

   Upload a receipt

   cURLNode.jsPythonPHP

   Copy

   curl https://api.fluveo.com/v1/files \
     -H "Authorization: Bearer sk_test_..." \
     -F purpose=dispute_evidence \
     -F "file=@receipt.pdf;type=application/pdf"

   import { readFile } from "node:fs/promises";
   
   const form = new FormData();
   form.append("purpose", "dispute_evidence");
   form.append("file", new Blob([await readFile("receipt.pdf")], { type: "application/pdf" }), "receipt.pdf");
   const response = await fetch("https://api.fluveo.com/v1/files", {
     method: "POST",
     headers: { Authorization: "Bearer sk_test_..." },
     body: form,
   });
   const file = await response.json();

   import requests
   
   with open("receipt.pdf", "rb") as document:
       file = requests.post(
           "https://api.fluveo.com/v1/files",
           headers={"Authorization": "Bearer sk_test_..."},
           data={"purpose": "dispute_evidence"},
           files={"file": ("receipt.pdf", document, "application/pdf")},
       ).json()

   <?php
   $ch = curl_init("https://api.fluveo.com/v1/files");
   curl_setopt_array($ch, [
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_POST => true,
       CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."],
       CURLOPT_POSTFIELDS => [
           "purpose" => "dispute_evidence",
           "file" => new CURLFile("receipt.pdf", "application/pdf", "receipt.pdf"),
       ],
   ]);
   $file = json_decode(curl_exec($ch), true);

2. Save a draft of your evidence#

   Post the evidence to the dispute with submit=false. Fluveo keeps it on the dispute and the bank sees nothing yet; post again to change it, until you submit.

   Save evidence as a draft

   cURLNode.jsPythonPHP

   Copy

   curl https://api.fluveo.com/v1/disputes/du_... \
     -H "Authorization: Bearer sk_test_..." \
     -H "Idempotency-Key: dispute-du-draft-1" \
     --data-urlencode "evidence[uncategorized_text]=The buyer received the order on 2 November." \
     -d "evidence[receipt]=file_..." \
     -d submit=false

   const response = await fetch("https://api.fluveo.com/v1/disputes/du_...", {
     method: "POST",
     headers: {
       Authorization: "Bearer sk_test_...",
       "Idempotency-Key": "dispute-du-draft-1",
     },
     body: new URLSearchParams({
       "evidence[uncategorized_text]": "The buyer received the order on 2 November.",
       "evidence[receipt]": "file_...",
       submit: "false",
     }),
   });

   import requests
   
   requests.post(
       "https://api.fluveo.com/v1/disputes/du_...",
       headers={
           "Authorization": "Bearer sk_test_...",
           "Idempotency-Key": "dispute-du-draft-1",
       },
       data={
           "evidence[uncategorized_text]": "The buyer received the order on 2 November.",
           "evidence[receipt]": "file_...",
           "submit": "false",
       },
   )

   <?php
   $ch = curl_init("https://api.fluveo.com/v1/disputes/du_...");
   curl_setopt_array($ch, [
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_POST => true,
       CURLOPT_HTTPHEADER => [
           "Authorization: Bearer sk_test_...",
           "Idempotency-Key: dispute-du-draft-1",
       ],
       CURLOPT_POSTFIELDS => http_build_query([
           "evidence[uncategorized_text]" => "The buyer received the order on 2 November.",
           "evidence[receipt]" => "file_...",
           "submit" => "false",
       ]),
   ]);
   curl_exec($ch);

3. Submit the evidence#

   Post the final evidence with submit=true. Leaving submit out submits too, so always send submit=false while you draft. After it is submitted, the evidence is fixed, and the dispute's status turns to under_review.

   Submit evidence

   cURLNode.jsPythonPHP

   Copy

   curl https://api.fluveo.com/v1/disputes/du_... \
     -H "Authorization: Bearer sk_test_..." \
     -H "Idempotency-Key: dispute-du-1-evidence" \
     -d "evidence[product_description]=Blue T-shirt, size M" \
     -d "evidence[customer_email_address]=buyer@example.com" \
     -d "evidence[shipping_tracking_number]=1Z999AA10123456784" \
     -d "evidence[uncategorized_text]=The buyer signed for the parcel on 2026-10-02." \
     -d submit=true

   const response = await fetch("https://api.fluveo.com/v1/disputes/du_...", {
     method: "POST",
     headers: {
       Authorization: "Bearer sk_test_...",
       "Idempotency-Key": "dispute-du-1-evidence",
     },
     body: new URLSearchParams({
       "evidence[product_description]": "Blue T-shirt, size M",
       "evidence[customer_email_address]": "buyer@example.com",
       "evidence[shipping_tracking_number]": "1Z999AA10123456784",
       "evidence[uncategorized_text]": "The buyer signed for the parcel on 2026-10-02.",
       submit: "true",
     }),
   });
   const dispute = await response.json();
   console.log(dispute.status);

   import requests
   
   response = requests.post(
       "https://api.fluveo.com/v1/disputes/du_...",
       headers={
           "Authorization": "Bearer sk_test_...",
           "Idempotency-Key": "dispute-du-1-evidence",
       },
       data={
           "evidence[product_description]": "Blue T-shirt, size M",
           "evidence[customer_email_address]": "buyer@example.com",
           "evidence[shipping_tracking_number]": "1Z999AA10123456784",
           "evidence[uncategorized_text]": "The buyer signed for the parcel on 2026-10-02.",
           "submit": "true",
       },
   )
   print(response.json()["status"])

   <?php
   $ch = curl_init("https://api.fluveo.com/v1/disputes/du_...");
   curl_setopt_array($ch, [
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_POST => true,
       CURLOPT_HTTPHEADER => [
           "Authorization: Bearer sk_test_...",
           "Idempotency-Key: dispute-du-1-evidence",
       ],
       CURLOPT_POSTFIELDS => http_build_query([
           "evidence" => [
               "product_description" => "Blue T-shirt, size M",
               "customer_email_address" => "buyer@example.com",
               "shipping_tracking_number" => "1Z999AA10123456784",
               "uncategorized_text" => "The buyer signed for the parcel on 2026-10-02.",
           ],
           "submit" => "true",
       ]),
   ]);
   echo json_decode(curl_exec($ch), true)["status"];

A submission sends every evidence field you saved: all your documents and all your texts. Each document is a PDF, JPEG or PNG of at most 5 MB, and the documents together are at most 4.5 MB and fewer than 50 pages. Text alone is a valid submission. If the bank cannot take what you sent, nothing is lost: the dispute keeps your evidence and goes back to needs_response with submission_count 0, a charge.dispute.updated says so, and the Dashboard shows why it was not sent. Fix it and submit again.

Once a submission has gone to the bank, the dispute takes no more evidence. Any new evidence, the same as before or different, with submit=true or submit=false, answers 400 "You've reached the maximum number of evidence submissions for this dispute." A post with only metadata still works, and sending the submission again with its first Idempotency-Key returns its first answer. One exception: when an inquiry you answered turns into a chargeback, the chargeback takes one more submission.

Evidence fields#

Each key goes in the form as evidence[<name>]. A text key takes plain text, and a file key takes the file_... id of an upload.

POST /v1/disputes/{id} takes these keys, submit and metadata, nothing else. Any other field, evidence[enhanced_evidence] included, is refused with a 400 whose param names it. Evidence that the case cannot take is refused the same way, so read param, fix that field and post again.

Accept a dispute#

When the buyer is right, or the order is not worth defending, call POST /v1/disputes/{id}/close with an Idempotency-Key. That gives the chargeback up for good: the buyer keeps the amount, the dispute ends as lost, and charge.dispute.closed reaches your endpoint. A closed dispute cannot be opened again.

curl -X POST https://api.fluveo.com/v1/disputes/du_.../close \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: dispute-du-1-close"

Test it#

In test mode, pay with one of the PaymentMethods below and a dispute opens on that charge by itself. It is already open when the payment's answer reaches you.

1. Create a PaymentIntent for amount=2000 (in the smallest unit of your currency) with payment_method_types[]=card, payment_method=pm_card_createDispute and confirm=true.
2. The dispute is already open when the payment answers: list GET /v1/disputes?payment_intent=pi_..., or catch charge.dispute.created on your endpoint, and save the dispute id.
3. Post evidence[uncategorized_text]=... with submit=false. The draft is kept and status stays needs_response.
4. Post it again with submit=true. charge.dispute.updated arrives and status is under_review.
5. Make a second pm_card_createDispute payment and call /close on its dispute. charge.dispute.closed arrives with status lost.

Next#

• Balance and payouts: what a dispute does to your balance and to your next payout.
• Refund a payment: refunding an unhappy buyer early can save you a dispute.
• The Disputes reference
• Event types