Stripe Connect Dispute Liability: Who Pays When a Buyer Charges Back

The architecture has four parts that have to be designed together: a liability map keyed on account-type plus charge-type, a webhook handler set that covers the full dispute lifecycle, an evidence submission pipeline that respects the card-network response window, and a vendor recovery worker that runs transfer reversals before the 180-day platform-reserve transfer fires.

Liability map in code, not in a wiki

Start with the liability map. Stripe's docs are explicit that for Standard accounts the connected account is liable for direct charges while the platform is liable for destination charges. For Express and Custom accounts the platform is typically responsible for handling disputes and refunds, with Express offering an opt-in to delegate that to the connected account through the Express Dashboard. The single rule that covers all destination charges and separate charges and transfers, regardless of account type, is that Stripe debits the dispute amount and the dispute fee from the platform account first.

| Account Type | Direct Charges | Destination Charges | Separate Charges + Transfers | |---|---|---|---| | Standard | Connected account liable | Platform debited first | Platform debited first | | Express | Platform liable (delegatable) | Platform debited first | Platform debited first | | Custom | Platform liable | Platform debited first | Platform debited first |

That table lives in your code as a function, not as a comment. Every place that creates a charge or handles a dispute consults it. The function takes the account type and the charge type and returns the liable party plus whether the platform balance gets debited at dispute time:

type AccountType = "standard" | "express" | "custom";
type ChargeType = "direct" | "destination" | "separate_charges_and_transfers";

interface LiabilityRule {
  liable_party: "platform" | "connected_account";
  platform_balance_debited_first: boolean;
  recovery_via_transfer_reversal: boolean;
}

function getLiabilityRule(
  accountType: AccountType,
  chargeType: ChargeType,
): LiabilityRule {
  if (accountType === "standard" && chargeType === "direct") {
    return {
      liable_party: "connected_account",
      platform_balance_debited_first: false,
      recovery_via_transfer_reversal: false,
    };
  }
  // Every other combination debits the platform first and requires
  // a transfer reversal to recover from the connected account.
  return {
    liable_party: "platform",
    platform_balance_debited_first: true,
    recovery_via_transfer_reversal: chargeType !== "direct",
  };
}

Webhook handler set across the lifecycle

Once that map is in code, the webhook handler set is straightforward. Stripe fires five dispute-related events, and a Connect platform needs handlers for at least three of them. charge.dispute.created is the legal event — the buyer has opened a dispute and the response clock is now running. charge.dispute.funds_withdrawn is the cash event — Stripe has pulled the money out of your account. charge.dispute.closed is the resolution event — the dispute ended in won, lost, or warning_closed. charge.dispute.updated and charge.dispute.funds_reinstated are useful for tracking but not strictly required.

The handler for charge.dispute.created does three things: it persists the dispute with a link to the original charge and the original transfer, it kicks off the evidence-gathering workflow with a deadline derived from the card network, and it determines whether the platform or the vendor should be notified to assemble the evidence. The lookup from charge to transfer is the one that needs to be fast and offline, because you will hit it on every dispute and you do not want to be making API calls under time pressure.

async function handleDisputeCreated(
  dispute: Stripe.Dispute,
  tx: DatabaseTransaction,
): Promise<void> {
  const charge = await tx.charges.findByStripeId(dispute.charge as string);
  if (!charge) {
    logger.error({ dispute_id: dispute.id }, "dispute on unknown charge");
    return;
  }

  const rule = getLiabilityRule(charge.account_type, charge.charge_type);

  await tx.disputes.insert({
    stripe_dispute_id: dispute.id,
    charge_id: charge.id,
    transfer_id: charge.transfer_id, // cached at charge-creation time
    connected_account_id: charge.connected_account_id,
    amount: dispute.amount,
    currency: dispute.currency,
    reason: dispute.reason,
    status: dispute.status,
    evidence_due_by: new Date(dispute.evidence_details.due_by * 1000),
    liable_party: rule.liable_party,
    requires_transfer_reversal: rule.recovery_via_transfer_reversal,
    state: "evidence_pending",
  });

  if (rule.liable_party === "platform") {
    await enqueueEvidenceWorkflow(dispute.id, charge);
  } else {
    await notifyConnectedAccountOfDispute(charge.connected_account_id, dispute);
  }
}

Funds-withdrawn as the deferred recovery trigger

The charge.dispute.funds_withdrawn handler is where the recovery worker gets kicked off. On a destination charge or a separate-charges-and-transfers flow, this is the moment the platform balance loses money. The handler records the cash impact in the platform's general ledger and, if the liability rule says the vendor should ultimately carry the loss, schedules a transfer reversal against the original transfer. The reversal is scheduled, not run immediately, because you generally want to wait until the dispute is closed before clawing the money back — winning the dispute reinstates the funds, and a premature reversal creates a vendor-balance hole that you then have to refund.

async function handleFundsWithdrawn(
  dispute: Stripe.Dispute,
  tx: DatabaseTransaction,
): Promise<void> {
  const record = await tx.disputes.findByStripeId(dispute.id);
  if (!record) return;

  await tx.disputes.update(record.id, {
    state: "funds_withdrawn",
    funds_withdrawn_at: new Date(),
  });

  await tx.ledger.insert({
    account: "platform_dispute_holding",
    direction: "debit",
    amount: dispute.amount,
    currency: dispute.currency,
    reference_type: "stripe_dispute",
    reference_id: dispute.id,
    memo: `Funds withdrawn for dispute ${dispute.id} on charge ${dispute.charge}`,
  });

  // Recovery is deferred to dispute close — we do not reverse the
  // transfer yet because winning the dispute reinstates the funds.
}

Dispute-closed branch on won vs lost

The charge.dispute.closed handler is where the dispute resolves into either a loss or a reinstatement. If the dispute is won or warning_closed, charge.dispute.funds_reinstated will fire and the platform balance gets the money back; the handler updates the case status and reverses the ledger entry. If the dispute is lost, the funds are permanently gone from the platform balance, and this is the moment the recovery worker runs. For account-type-plus-charge-type combinations where the rule says to recover from the vendor, the handler creates a transfer reversal against the original transfer ID. If the vendor's balance does not have enough to cover the reversal, Stripe will let the account go negative — and from there the negative-balance recovery flow takes over.

async function handleDisputeClosed(
  dispute: Stripe.Dispute,
  tx: DatabaseTransaction,
): Promise<void> {
  const record = await tx.disputes.findByStripeId(dispute.id);
  if (!record) return;

  await tx.disputes.update(record.id, {
    state: dispute.status, // "won" | "lost" | "warning_closed"
    closed_at: new Date(),
  });

  if (dispute.status === "lost" && record.requires_transfer_reversal) {
    await scheduleTransferReversal({
      transfer_id: record.transfer_id,
      amount: dispute.amount,
      description: `Recovery for lost dispute ${dispute.id}`,
    });
  }
}

Evidence pipeline with one-shot submission

The evidence submission pipeline is where most teams cut corners and then regret it. Stripe gives you one submission per dispute — there is no way to add files after the initial response — so the pipeline needs to gather everything before it submits. The deadline is read from evidence_details.due_by on the dispute object, and the pipeline needs to enforce a soft deadline at 24 to 48 hours before that hard deadline so a human has time to review. Mastercard caps the combined evidence file at 19 pages, so the assembler needs format-aware truncation, not just byte-count truncation. A pipeline that submits a 21-page PDF to Mastercard will silently fail validation and burn the only submission you get.

Vendor recovery worker and the negative-balance path

For the vendor recovery path, the transfer reversal API is the only mechanism that moves money from the connected account back to the platform balance after a destination charge dispute. The reversal can be partial or full, and it carries the same currency as the original transfer. The worker that runs the reversal needs to handle the case where the vendor's balance is insufficient — Stripe will let the account go negative, and the negative-balance recovery flow then runs against the vendor's external bank account (where the region supports automatic debit) before the 180-day platform-reserve transfer fires. Building the worker to log every step of that chain — reversal attempted, vendor balance before and after, external account debit attempted, residual negative balance — is what gives finance the audit trail they need to write off the loss correctly when it does land.