Refunds, Chargebacks, and Disputes

Pathrule3 Rules • 3 Memories • 2 Skills

Refunds and disputes reverse value through different actors, timelines, and evidence requirements. This bundle preserves the original charge, separates requested and confirmed refunds, models dispute deadlines and evidence, posts compensating ledger entries, and keeps customer access decisions explicit. Unlike Dunning and Churn Recovery, it governs post-payment reversals and claims rather than failed recurring collection.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

src/

payments/

refunds/

Create one refund intent before calling the provider

Refund reason taxonomy drives reporting and controls

audit-refund-controls

disputes/

Dispute cases preserve deadlines and evidence provenance

Money reversal and product access are separate decisions

ledger/

Post reversals without rewriting the original payment

ops/

risk/

Dispute state is a timeline, not the latest webhook label

prepare-dispute-evidence

Rules

Create one refund intent before calling the provider/src/payments/refundshighstrictA refund begins as an idempotent internal intent with amount, currency, allocation, reason, and actor before external mutation.

1	A refund API response can time out after the processor accepted the request, and support may retry from another screen. Create one internal refund intent first with a stable operation key, original charge, amount, currency, affected items, reason, actor, and expected allocation. Reuse that intent until the provider outcome is known.
2
3	- Validate cumulative confirmed and pending refunds against the refundable amount in the original currency.
4	- Send the stable idempotency key on every provider retry and resolve ambiguity by provider lookup.
5	- Distinguish requested, submitted, pending, succeeded, failed, canceled, and reversed states instead of setting refunded immediately.
6	- Authorize partial and full refunds through explicit policy and preserve the original charge unchanged.
7
8	Verification: Inject timeouts before and after provider acceptance, race two agents, and attempt overlapping partial refunds; confirm at most one external mutation per intent.

Dispute cases preserve deadlines and evidence provenance/src/payments/disputeshighstrictEvery dispute records the provider deadline, current stage, claim reason, evidence sources, submission receipt, and accountable owner.

1	A dispute is a time-bounded case, not a boolean on a payment. Capture each provider event, deadline, reason code, contested amount, currency, liability, and current stage in an append-only case timeline. Evidence must be traceable to its source and reviewed for relevance, accuracy, privacy, and provider limits before submission.
2
3	- Assign an owner and escalation clock as soon as a dispute or inquiry becomes actionable.
4	- Store hashes or immutable references for submitted documents and the exact field set accepted by the provider.
5	- Never fabricate, backdate, or alter customer communications to improve a case.
6	- Record whether the case was accepted, lost, won, withdrawn, or moved to another stage and retain the provider receipt.
7
8	Verification: Simulate duplicate events, an updated deadline, partial evidence failure, and a late case; confirm the timeline, alerting, and submission record remain coherent.

Post reversals without rewriting the original payment/src/ledgerhighstrictRefunds, dispute withdrawals, fees, wins, and losses create linked compensating entries in the original transaction currency.

1	The original charge remains historical truth even when value later moves back. Post a linked set of immutable entries for refund principal, non-returned fees, dispute withdrawal, dispute fee, provisional credit, reversal, win, or loss as the provider lifecycle requires. Keep provider effective time separate from the business decision time.
2
3	- Balance each posting set per currency and store the original payment, refund, dispute, and balance movement references.
4	- Represent partial outcomes explicitly instead of replacing a payment status or netting unrelated cases.
5	- Use actual settlement conversion evidence for cross-currency bank effects while retaining the original transaction currency.
6	- Reconcile every provider balance movement to exactly one recognized internal intent or classified exception.
7
8	Verification: Replay a partial refund, a lost dispute, a won dispute with fee treatment, and a reversed refund; confirm the original payment is unchanged and totals reconcile.

Memories

Money reversal and product access are separate decisions/src/payments/disputesA refund or dispute changes financial state, while access follows a documented fulfillment, fraud, service, and legal policy.

1	Do not let a provider status directly delete user data or revoke product access. A full refund may end a future service, a partial refund may not change access, an inquiry may require only monitoring, and a dispute may trigger a temporary risk hold while evidence is reviewed. Define these outcomes by product type, fulfillment state, fraud signal, contractual terms, and applicable policy.
2
3	Store the policy version and reason behind every access transition, make the action reversible where possible, and preserve customer data under retention rules rather than destructive shortcuts. Notify the customer through approved language when required and separate support visibility from sensitive risk notes. See /src/ledger for financial postings and /ops/risk for case handling evidence.

Refund reason taxonomy drives reporting and controls/src/payments/refundsCustomer-facing explanations, internal root causes, fraud signals, and accounting treatment use separate controlled reason fields.

1	One free-form refund reason cannot serve the customer, support, product, risk, and finance at the same time. Keep a controlled internal reason code, optional subreason, customer-visible explanation, actor note, affected items, and evidence reference as separate fields. Version the taxonomy so historical reporting does not change when labels are reorganized.
2
3	Use reason codes to route approval thresholds, fraud review, supplier recovery, product defect follow-up, and accounting treatment, but never let a code alone authorize money movement. Restrict sensitive risk notes from customer-facing exports and analytics with broad access. Review high use of generic or other codes as a data-quality failure. See /ops/risk for dispute evidence handling and /src/ledger for financial classification.

Dispute state is a timeline, not the latest webhook label/ops/riskInquiry, warning, formal dispute, evidence review, provider decision, appeal, and financial settlement can progress on different clocks.

1	The latest provider label may omit earlier deadlines, provisional withdrawals, reopened stages, appeal rights, or final settlement timing. Preserve every state transition and provider event with effective time, received time, evidence deadline, actionability, financial effect, and source id. Derive the current case view from that timeline without deleting superseded facts.
2
3	Keep operational status separate from ledger settlement: a case can be won while a fee remains, or decided before money returns. Alert from the authoritative deadline and require explicit acknowledgment, ownership transfer, and escalation. Map provider-specific reason and stage values to an internal model while retaining the raw value. See /src/payments/disputes for submission evidence and /src/ledger for money effects.

Skills

prepare-dispute-evidence/ops/riskBuild a truthful, minimal, deadline-aware dispute case from retained order, identity, delivery, and communication evidence.

1	---
2	name: prepare-dispute-evidence
3	description: Build a truthful and deadline-aware payment dispute evidence package from retained records.
4	---
5
6	# Prepare Dispute Evidence
7
8	1. Confirm provider case id, reason, stage, contested amount, currency, response deadline, owner, and the exact evidence fields allowed.
9	2. Assemble only relevant records from the original order, payment authorization, customer identity checks, terms acceptance, delivery or usage, refund policy, and communications.
10	3. Verify timestamps, identities, document provenance, completeness, and privacy; remove unrelated personal or secret data.
11	4. Write a concise case narrative that connects each claim to attached evidence without inventing intent or altering source material.
12	5. Submit before the internal cutoff, retain the exact payload and provider receipt, and schedule outcome follow-up.
13
14	If evidence is missing or contradictory, record that limitation and escalate. Never create retrospective evidence to fill a gap.

audit-refund-controls/src/payments/refundsReview refund authorization, idempotency, cumulative limits, provider reconciliation, access effects, and ledger postings.

1	---
2	name: audit-refund-controls
3	description: Review refund authorization, idempotency, limits, reconciliation, and downstream effects.
4	---
5
6	# Audit Refund Controls
7
8	1. Trace full and partial refunds from support or API request through authorization, internal intent, provider call, webhook confirmation, customer notice, access policy, and ledger posting.
9	2. Test duplicate clicks, concurrent agents, network timeouts, provider retry, stale order state, currency mismatch, and cumulative over-refund attempts.
10	3. Compare internal refund records with provider refunds and balance movements, then classify every missing, duplicate, failed, reversed, or amount-different case.
11	4. Sample approved refunds for actor, reason, evidence, policy version, item allocation, and immutable audit history.
12	5. Record control failures, affected period and amount, remediation owner, and proof from a clean rerun.
13
14	A green audit requires explainable money movement, not merely matching order labels.

Why this pattern

Agents mark an order refunded before money moves, overwrite the original charge, miss dispute deadlines, or revoke access inconsistently across partial and contested reversals.

Built for Payments, support, risk, and finance teams handling refunds, chargebacks, inquiries, and payment disputes.

Keeps your assistant from:

Duplicate refunds after timeout or support retries
Dispute evidence submitted late or without a reproducible case file
Ledger and customer access state disagreeing with provider outcomes

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25