Disputes

Overview

A dispute occurs when a customer challenges a payment made through your site — for example, when they contact their bank to contest a charge. Disputes originate only on the payment processor’s side, and Pelcro listens to the payment processor webhooks to reflect their final status.

Pelcro itself does not initiate or manage disputes. Instead, it flags the charge as disputed when notified by the payment processor and temporarily restricts any actions on that charge until the dispute is resolved.

Note: Disputes are currently supported for Stripe payments only. For questions or assistance, please contact [email protected].


What Is a Dispute

A dispute represents a formal claim by a customer against a payment they made — often referred to as a chargeback. When a dispute is created in Stripe, the payment is temporarily placed under review by the card issuer.

“I paid for something, but now I’m challenging that payment.”


Where Disputes Are Managed

Disputes are handled on the payment processor’s side, where the investigation, evidence submission, and resolution take place. Pelcro automatically listens for dispute events from supported processors and updates your platform to keep records accurate.

Within Pelcro, disputed charges are clearly flagged as disputed and locked to prevent conflicting actions (such as refunds or adjustments) while the processor reviews the case. This ensures your accounting data and customer records remain consistent throughout the dispute process.

The Payments export also reflects these cases by marking the charge under the disputed column as true.


How Pelcro Handles Disputes

Pelcro listens to Stripe’s dispute webhook events and updates records accordingly. We do not mirror the ongoing dispute lifecycle, but take action when key Stripe events occur.

Stripe EventAction in PelcroDescription
charge.dispute.createdMark charge as disputedThe charge is locked — no refunds or manual actions can be taken while the dispute is open.
charge.dispute.closedSync final outcomeOnce the dispute is closed, Pelcro checks the status field and updates records if the dispute was lost (refund created) or won (no change).

Lifecycle of a Dispute

Here’s how Stripe disputes flow through Pelcro:

  1. Customer initiates a dispute via their bank or card issuer.
  2. Stripe sends charge.dispute.created to Pelcro.
    • Pelcro flags the charge as disputed = true.
    • The charge becomes read-only — no refunds or actions can be performed in Pelcro.
    • The charge remains in Paid status.
  3. Stripe investigates and sends charge.dispute.closed once the dispute is resolved.
  4. Based on the outcome:
    • Dispute won (merchant): No changes. The payment remains Paid, since funds were retained.
    • Dispute lost (customer): Pelcro creates a refund object to record the reversal and keep accounting in sync.

Example Timeline

StageStripe EventPelcro ActionStatus
Dispute createdcharge.dispute.createdMark charge as disputed; freeze actions⚠️ Disputed
InvestigationCharge locked in Pelcro — charge remains Paid⚙️ In Review
Dispute woncharge.dispute.closed (status = won)No change — charge remains Paid✅ Won
Dispute lostcharge.dispute.closed (status = lost)Create Refund record❌ Lost

Impact on Accounting & Reports

ScenarioAccounting BehaviorExports & Visibility
Dispute OpenedNo ledger movement. Charge remains visible as paid.The Payments export marks the charge under the disputed column as true.
Dispute Won (merchant)No changes; funds remain recorded as received.No refund record created.
Dispute Lost (customer)Pelcro creates a refund object to match Stripe’s refund and maintain ledger accuracy.Accounting exports reflect the refund created.

Pelcro’s ledger system (Online Cash, AR, and Customer Balance) treats lost disputes as normal refund transactions to ensure accurate accounting.


Subscription & Customer Impact

  • Pelcro does not automatically pause or cancel subscriptions when a dispute occurs.
  • Customer records remain active, but the disputed payment is tagged as “Disputed” in the UI.

Next Steps

  • Need help or have questions about a dispute? Contact our support team at [email protected] — we’re here to assist.