Disputes

A dispute begins when a buyer or their bank challenges a payment. Flint records the case, its response deadline, the disputed amount, and its relationship to the original payment and order. Use the API and webhooks to drive your operational queue. Evidence responses are completed in the Flint dashboard.

Build the Response Queue#

Subscribe to dispute.created, dispute.updated, and dispute.closed. Also subscribe to the more specific outcome events if your accounting or fulfillment systems need them: dispute.needs_response, dispute.won, dispute.lost, and dispute.prevented.

Webhook deliveries can be duplicated or arrive after a newer observation. Treat the event as a prompt to retrieve the current dispute resource, and deduplicate deliveries by webhook_event_id (the same value as the webhook-id header).

curl https://api.withflintpay.com/v1/disputes/dsp_1kmn0aExample \
  -H "Authorization: Bearer YOUR_API_KEY"

The API key needs payments.disputes.read. Store the following fields with your case:

• status and action_required, which determine whether work remains.
• evidence_due_at, evidence_response_allowed, and evidence_deadline_passed, which define the response window.
• reason and case_type, which determine the evidence package to prepare. case_type also distinguishes early warning and inquiry cases from formal chargebacks, and marks an ACH return as bank_return (see Bank Returns).
• payment_option, the payment option the disputed payment used, such as card, apple_pay, or ach_debit.
• payment_intent_id, order_id, customer_id, and amount_money, which connect the case to fulfillment and accounting records.
• fraud_warning_id, when an earlier issuer fraud warning preceded the dispute.

GET /v1/disputes supports these filters:

• status, reason, case_type: dispute classification.
• payment_intent_id, order_id, customer_id: scope to a payment, order, or customer.
• created_after, created_before: creation time window.
• evidence_due_after, evidence_due_before: evidence deadline window.

A daily deadline queue can request cases due within a bounded window:

curl --get https://api.withflintpay.com/v1/disputes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "status=needs_response" \
  --data-urlencode "evidence_due_before=2026-07-15T00:00:00Z" \
  --data-urlencode "page_size=100"

Continue with page_token until next_page_token is absent. Do not retain a page token after changing any filter.

Bank Returns#

An ACH debit payment that fails after settling comes back as a bank return, and Flint represents it with the same Dispute resource. A return case has:

• case_type: bank_return.
• payment_option: ach_debit.
• reason: insufficient_funds, bank_debit_not_authorized, bank_account_not_found, or other.
• No response window: evidence_response_allowed and action_required are false, and evidence_due_at is null.

A bank return is final when it arrives: dispute.created, dispute.closed, and dispute.lost fire together, and there is no evidence to prepare or outcome to influence. Route these cases to accounting and buyer outreach instead of your evidence queue; filter on case_type so returns never appear as work waiting on a deadline. The returned funds have already left your balance, so collecting again means a new payment from the buyer, not a case response.

A bank return also reduces what remains refundable on the payment. See Refunds for how bank returns and refunds interact.

Neither a dispute nor a bank return revises the processing fee already charged on the original payment. Both do carry a separate event fee: $15.00 for a bank return or other dispute on an ACH payment, and the card network's own dispute cost passed through without markup on a card, Apple Pay, or Google Pay payment. Event fees are assessed against your merchant account rather than deducted from the disputed movement, so read them on merchant billing rather than on the balance transaction. See Processing Fees.

Prepare Evidence#

Start from the dispute reason instead of sending every document available. A concise, internally consistent response is easier to evaluate than an unrelated document dump.

For an unrecognized or fraudulent payment, collect customer identity and communication, authentication results, device or IP context you lawfully retain, prior undisputed transactions, and proof that the buyer received the product or service. Do not present a risk score alone as proof that the buyer authorized the payment.

For product-not-received cases, collect the order confirmation, fulfillment timeline, carrier tracking, delivery address, delivery confirmation, and buyer communication. For duplicate or incorrect-amount cases, show each transaction, invoice, refund, and the calculation that distinguishes the legitimate charge. For canceled subscriptions, include the accepted cancellation policy, cancellation timestamp, service period, and communications about renewal.

Open the dispute in the Flint dashboard to upload and submit evidence. After submission, keep listening for updates. under_review means no further response is currently required; it does not predict the outcome.

Handle the Result#

Terminal statuses are won, lost, and prevented. Warning cases can also close without becoming formal chargebacks. Reconcile the final state against the payment, order, balance transactions, and any refund already issued. Do not issue an additional refund merely because a case is lost; first verify the authoritative payment and refund totals.

When a dispute is fraudulent, review related saved payment methods, active sessions, unfulfilled orders, and subscriptions. Close operational access only when your own policy supports it. A dispute result is a payment signal, not proof that every action from the same customer is fraudulent.

Fraud Warnings#

An issuer fraud warning can arrive before a dispute. fraud_warning.created includes an immutable payment summary and an actionable flag. A full refund or a linked dispute makes it unactionable, and fraud_warning.updated reports that transition.

For an actionable warning, pause fulfillment when appropriate and inspect the payment. If your policy calls for a proactive refund, create it through the refunds API with reason fraudulent. Re-read the payment first so a concurrent refund does not cause an over-refund.

Next Steps#

• Webhooks: signature verification and retry-safe handling of dispute.* events.
• Refunds: refund semantics, including refunds blocked by an open dispute.
• Risk Controls: fraud warning and payment review workflows.
• Error Handling: the error envelope and retry strategy.