ALwrity/docs/Billing_Subscription/stripe-ops-guide.md

Stripe Billing & Subscriptions – Ops Team Guide

This guide is for non-technical operations and support staff. It explains how to use ALwrity’s internal Stripe tools to review payments, handle disputes, and respond to early fraud warnings.

You do not need to use the Stripe Dashboard for day-to-day work; use the internal tools described here.

---

1. Where to go in the app

• Sign in to ALwrity with your admin account.
• Open the internal Stripe dashboard:
  • URL: /stripe-disputes
• You will see two tabs:
  • Disputes – for chargebacks / disputes raised by card issuers.
  • Fraud Warnings – for early fraud warnings (EFWs) where issuers suspect fraud before a dispute is filed.

If you cannot access this page:

• Your account might not be whitelisted as an admin. Contact the engineering team to check your email and role.

---

2. Disputes Tab – Handling Chargebacks

When a customer disputes a payment with their bank, Stripe creates a Dispute. The Disputes tab helps you:

• See all disputes.
• Review details (amount, reason, charge ID).
• Submit evidence.
• Close disputes when needed.

2.1 Disputes List

The table shows:

• ID – Stripe’s dispute ID (useful if support needs to talk to Stripe).
• Amount – Disputed amount.
• Status – Current status (e.g. needs_response, under_review, won, lost).
• Reason – Bank’s reason (e.g. fraudulent, product_not_received).
• Charge – The related Stripe charge ID.
• Created – When the dispute was created.

Actions:

• Refresh disputes – Reloads the list from Stripe.
• Details – Opens the dispute details dialog.
• Close – Shortcut to close the dispute (same as “Close Dispute” inside the dialog).

2.2 Dispute Details & Evidence

When you click Details, you see:

• ID / Amount / Status / Reason / Charge / Created – Basic information summarizing the case.
• Fraud Type – A dropdown where you classify the dispute:
  • Card testing – many small rapid attempts, usually bots testing cards.
  • Stolen card – customer’s card was used without permission.
  • Overpayment fraud – customer overpays and asks for a refund via another method.
  • Alternative refund – customer tries to get a payout via cash/crypto/bank transfer instead of back to card.
  • Other – anything else.
• Customer Email / Name / IP – Fields to record known customer details.
• Access Activity Log – Summary of account activity:
  • Example:
    • "User logged in from IP 1.2.3.4, created 3 projects, downloaded 2 reports."
• Fraud Indicators / Notes – A free text area where you:
  • Summarize what looks suspicious (or legitimate).
  • Mention patterns like:
    • Many failed attempts before one success.
    • Overpayment + request for alternate refund.
    • Different billing and login locations.

Buttons:

• Submit Evidence
  • Sends your evidence to Stripe for this dispute.
  • Use this when you want to contest the dispute and show that the charge is valid.
• Close Dispute
  • Tells Stripe you are not going to submit more evidence.
  • Use this if:
    • The dispute is clearly correct (e.g. genuine mistake).
    • The amount is lower than the dispute fee and not worth contesting.

Tips:

• Be specific and factual in evidence:
  • “User logged in and used the product for 3 days” is better than “Looks fine”.
• Use the Fraud Type dropdown to tag cases consistently; it helps the team see patterns.

---

3. Fraud Warnings Tab – Early Fraud Warning (EFW)

An Early Fraud Warning is a signal from the card issuer that a charge may be fraudulent, before a dispute is created.

The Fraud Warnings tab helps you:

• See EFWs for our charges.
• Decide whether to proactively refund to avoid a later dispute.
• Record decisions and notes.

3.1 Fraud Warnings List

Columns:

• ID – The Early Fraud Warning ID from Stripe.
• Charge – Related Stripe charge ID.
• Amount – Charge amount.
• Status – Our internal status:
  • open – Needs review.
  • refunded – We proactively refunded the card.
  • ignored – We reviewed and decided not to refund.
• Action – The latest action taken (none, refund_full, ignored).
• Created – When the warning was created.

Actions:

• Refresh warnings – Reloads current open warnings.
• Details – Opens the warning details dialog.

3.2 Fraud Warning Details and Actions

Inside the details dialog you see:

• ID / Charge / Amount – Basic reference info.
• Status / Action – Current state and last action taken.
• Created / Last Action At – Timeline.
• Issuer Fraud Type – What the bank believes is happening (e.g. made_with_stolen_card).
• Actionable – Indicates whether Stripe considers this warning still actionable:
  • “Yes” – No full refund yet and no dispute; you can still act.
  • “No” – It has either been refunded or disputed already.
• Action Notes – Free text for internal reasoning.

Buttons:

• Refund Full Amount
  • Sends a full refund for the underlying charge via Stripe.
  • Sets status to refunded and action to refund_full.
  • Use this when:
    • The charge amount is relatively small (similar to or less than your dispute fee).
    • The warning and behavior strongly suggest fraud (e.g. stolen card, clear card testing).
• Mark as Ignored
  • Marks the warning as ignored without refund.
  • Use this when:
    • You believe the charge is legitimate.
    • The user has confirmed the purchase, or your internal logs show normal behavior.
• Close
  • Closes the dialog only (no changes to Stripe or status).

Notes:

• You can add or update Action Notes before clicking Refund or Mark as Ignored:
  • Example:
    • "Customer confirmed via support email that they made this purchase."
    • "High risk: many failed attempts, unusual IP, amount small – refunding to avoid dispute."

---

4. How to Decide: Refund vs Ignore

These are general guidelines; when in doubt, coordinate with product/engineering.

4.1 When to Consider Proactive Refund

• The amount is small, roughly in the range of the expected dispute fee.
• The pattern clearly matches fraud:
  • Many rapid attempts with different cards or card numbers.
  • Charge is from a suspicious IP/country inconsistent with user profile.
  • Issuer fraud type suggests stolen or counterfeit card.
• The user is not reachable or does not respond to your messages.

In these cases:

• Use Fraud Warnings → Details → Refund Full Amount.
• Add a short note explaining why:
  • "EFW flagged as made_with_stolen_card; small charge; refunding proactively."

4.2 When to Ignore (No Proactive Refund)

• The customer confirms they made the purchase.
• Your logs show normal use of the product:
  • Regular logins, content creation, downloads.
• Amount is large and there is no strong sign of fraud:
  • In this case you typically wait and, if a dispute occurs, respond with strong evidence.

In these cases:

• Use Fraud Warnings → Details → Mark as Ignored.
• Add notes:
  • "Customer confirmed via email; usage patterns normal; ignoring EFW."

---

5. Things You Should Not Do

• Do not send refunds via:
  • Bank transfer
  • Cash
  • Crypto
  • Any method outside Stripe

Always refund via Stripe so:

• The cardholder is repaid correctly.
• Issuers see the refund related to the original charge.

If someone asks for a different refund method, treat it as a potential overpayment or alternative refund scam and escalate to the team.

---

6. When to Escalate to Engineering

Contact engineering when:

• You see a sudden spike in disputes or fraud warnings.
• The internal dashboard shows errors when:
  • Loading disputes/fraud warnings.
  • Submitting evidence.
  • Refunding/ignoring warnings.
• You need a new flow:
  • Example: new product or plan changes that alter how subscriptions work.

Provide:

• Screenshot of the issue.
• Dispute ID or Fraud Warning ID.
• A short description of what you were trying to do.

---

7. Quick Reference

• Disputes Tab
  • Use to respond to formal disputes.
  • Add evidence and close disputes when appropriate.
• Fraud Warnings Tab
  • Use to review early fraud warnings.
  • Decide whether to refund or ignore.
• Action Notes
  • Always record a short reason when you refund or ignore.

If you follow this guide, you will help protect the business from fraud while treating legitimate customers fairly.