WF-118: Billing Dispute Resolution

Workflow ID: WF-118 Category: Billing Priority: P2 Last Updated: January 11, 2026

---

Overview

This workflow handles billing disputes from submission through investigation to resolution, including credit or refund processing via Stripe.

---

Trigger Events

• User submits billing dispute
• Chargeback received from Stripe
• Support ticket flagged as billing
• Automated anomaly detection

---

Sequence Diagram

---

Process Steps

1. Dispute Submission

User Information Required:

Field	Required	Description
Invoice/Charge ID	Yes	Which charge is disputed
Dispute reason	Yes	Category selection
Amount disputed	Yes	Full or partial
Description	Yes	Detailed explanation
Evidence	No	Screenshots, emails

Dispute Categories:

Category	Examples
Incorrect charge	Wrong amount, duplicate
Service not received	Feature not working
Unauthorized	Didn't authorize charge
Cancellation not processed	Charged after cancel
Other	Requires description

2. Investigation

Investigation Steps:

1. Charge Verification

   • Pull charge from Stripe
   • Verify charge timestamp
   • Check linked invoice

2. Service Verification

   • Check usage logs
   • Verify service delivery
   • Review subscription history

3. Communication History

   • Check support tickets
   • Review cancellation requests
   • Verify email confirmations

Investigation Timeline:

Phase	Duration	Action
Acknowledgment	1 business day	Confirm receipt
Investigation	5-7 business days	Research claim
Resolution	2 business days	Process outcome

3. Resolution Determination

Resolution Options:

Resolution	When Applied
Full refund	Charge clearly incorrect
Partial refund	Partial service delivery
Account credit	Service issue, user to continue
No action	Charge valid, well documented
Escalation	Complex or legal involvement

Approval Authority:

Amount	Approver
< $100	Support Lead
$100-$500	Finance Team
$500-$1000	Finance Manager
> $1000	CFO/Executive

4. Credit Processing

Account Credit:

{
  "credit_id": "cred_123",
  "user_id": "usr_456",
  "amount_cents": 5000,
  "reason": "Service disruption Jan 5-7",
  "dispute_id": "disp_789",
  "expires_at": null,
  "applied_to": null
}

Credit Application:

• Automatically applied to next invoice
• Visible in billing dashboard
• Never expires (unless specified)

5. Refund Processing

Refund via Stripe:

{
  "refund_id": "re_123",
  "charge_id": "ch_456",
  "amount_cents": 9900,
  "reason": "requested_by_customer",
  "status": "succeeded",
  "destination": "original_payment_method"
}

Refund Timeline:

• Credit card: 5-10 business days
• Bank transfer: 3-5 business days
• Appears on statement as: "CODITECT REFUND"

---

API Endpoints

Endpoint	Method	Purpose
/api/v1/billing/disputes	POST	Submit dispute
/api/v1/billing/disputes/{id}	GET	Get dispute status
/api/v1/billing/disputes/{id}/evidence	POST	Add evidence
/api/v1/billing/credits	GET	List credits
/api/v1/billing/refunds	GET	List refunds

Request: Submit Dispute

POST /api/v1/billing/disputes
{
  "charge_id": "ch_456",
  "category": "incorrect_charge",
  "amount_cents": 9900,
  "dispute_full_amount": true,
  "description": "I was charged twice for the same month",
  "evidence": {
    "email_confirmations": ["file_id_1"],
    "screenshots": ["file_id_2"]
  }
}

Response

{
  "dispute_id": "disp_789",
  "status": "submitted",
  "charge_id": "ch_456",
  "amount_cents": 9900,
  "category": "incorrect_charge",
  "created_at": "2026-01-11T12:00:00Z",
  "estimated_resolution": "2026-01-18T12:00:00Z",
  "ticket_id": "TICK-12345"
}

---

Email Notifications

Dispute Received

Subject: We received your billing dispute #[DISPUTE_ID]

Hi [Name],

We've received your billing dispute for $[AMOUNT].

Dispute ID: [DISPUTE_ID]
Charge: [CHARGE_DESCRIPTION]
Status: Under Investigation

We'll update you within 5-7 business days.

Track status: [DISPUTE_URL]

Dispute Resolved - Approved

Subject: Your billing dispute has been resolved - Credit/Refund approved

Hi [Name],

Good news! We've resolved your dispute in your favor.

Resolution: [CREDIT/REFUND]
Amount: $[AMOUNT]
Applied: [DATE/METHOD]

[For credit]: This will apply to your next invoice.
[For refund]: Allow 5-10 days to appear on your statement.

Thank you for your patience.

Dispute Resolved - Denied

Subject: Update on your billing dispute

Hi [Name],

We've completed our investigation of dispute #[ID].

After review, we were unable to issue a credit/refund because:
[REASON]

If you have additional information, you may:
- Reply to this email with evidence
- Request escalation within 30 days

Charge details: [INVOICE_URL]

---

Error Handling

Error	Cause	Resolution
CHARGE_NOT_FOUND	Invalid charge ID	Verify charge exists
DISPUTE_EXISTS	Duplicate dispute	Reference existing
CHARGE_TOO_OLD	Outside dispute window	Deny with explanation
REFUND_FAILED	Stripe error	Manual processing

---

Audit Events

Event	Logged
dispute.submitted	User, Charge, Amount
dispute.evidence_added	Dispute ID, File IDs
dispute.investigation_started	Assignee
dispute.resolved	Resolution, Amount, Approver
credit.issued	Amount, Dispute ID
refund.processed	Stripe refund ID, Amount

---

Related Workflows

• WF-112: Subscription Downgrade
• WF-117: Account Recovery
• WF-119: Resource Quota Management

---

Last Updated: January 11, 2026