# Chargeback simulation — demo walkthrough

For showing the client how a **cardholder dispute** travels through the portal, before any real scheme connection exists.

> **Be upfront with the client:** the chargebacks are simulated. They are fabricated on real test transactions and enter through the same intake a real scheme file would use. The scheme file formats are *not* the schemes' real formats; those come from scheme onboarding.

---

## The story you are telling

1. A **cardholder** disputes a purchase with **their bank** (the issuer).
2. The issuer sends it to the **card scheme**, which sends it to Mercury (the **acquirer**) as a **chargeback**.
3. The portal creates a case. **The merchant is debited straight away.**
4. Our team works it: collects the merchant's evidence, gets approvals, and answers the scheme.
5. The **scheme decides.** If the merchant wins, the money is **credited back**. If not, the debit stands.
6. Everything is recorded: who did what, when, and every money movement.

---

## Before the demo (once)

| Step | Where |
|---|---|
| Sign in as a user with **`dispute.config.manage`** (e.g. a Dispute Head or superuser) | |
| Make sure the money rule is **ON** | **Disputes → Rules & SLA → Dispute Parameters** → tick **"Debit the merchant when a chargeback arrives; credit back if it is won"** → Save |
| (Optional) set **Compliance review** to **Off** so the demo isn't held up by a compliance step | Same page |

The money rule is **off by default** because it changes what merchants are paid. It affects only chargebacks that arrive after it is switched on.

---

## The demo, step by step

Open **Disputes → Workflow → Scheme Simulator** (`/admin/chargebacks/simulator`).

### 1. A scheme sends chargebacks
- Choose a **scheme** (e.g. Mastercard), set **how many** (try 2), press **Receive chargebacks**.
- The page shows: "Mastercard 'sent' 2 chargeback(s)", the **file the scheme "sent"** (so you can show what a scheme file looks like), and the new cases in the table.
- Say: *"This is the same intake a real scheme file or API feed would use. The case is created, the original transaction is put on chargeback hold, and the merchant is debited."*

### 2. See the money move
- In the table, the **Merchant money** column shows **`DEBIT 310.50 AED`** against each case.
- Say: *"The moment the chargeback arrives, the merchant is debited. We are not carrying the exposure while we fight it."*

### 3. Work the case
- Click the case number to open it on the **Dispute Dashboard**.
- Show: transaction details, **Merchant money** panel, **timeline** (with the money step), **evidence** upload, **assign / escalate**, and — for large amounts — the **approval** and **compliance** steps.
- Show **Representment** (the response filed to the scheme).

### 4. The scheme decides
- Back on the simulator, press **Merchant wins** on one case and **Merchant loses** on another.
- **Merchant wins** → the column now also shows **`CREDIT 310.50 AED`**: the merchant is paid back.
- **Merchant loses** → the debit stands; nothing more is posted.
- Say: *"Whatever the scheme decides is applied the same way a real network result would be."*

### 5. Show the record
- Open each case again: the **timeline** shows every step, including *"credited back 310.50 AED to the merchant"*.
- **Disputes → Dispute Analytics / Win Rate Analytics** show the outcome in the numbers.

---

## Showing the files

- On the simulator page: **Sample files to show the client** — one download per scheme (Mastercard, Visa, JCB, Amex, UnionPay).
- The same files are in `docs/Dispute-Management/samples/` with a README explaining each column.
- To load a sample: **Dispute Dashboard → Import CSV**.

---

## What to say if asked

| Question | Honest answer |
|---|---|
| "Is this how Visa/Mastercard really send disputes?" | The *content* is realistic. The *file format and channel* are not — those come from each scheme during onboarding. Mercury is a direct member, so each scheme will give us a channel (API, SFTP files, or a scheme tool). We build a reader per scheme once we have their real sample. |
| "Does money really move?" | It creates a **settlement adjustment** (an approved debit/credit) — the same mechanism Finance already uses. It is paid out with the merchant's settlement, not instantly. See the limits below. |
| "Which schemes work today?" | The simulator covers all five. For real intake, Mastercard has an API connection to Mastercard's **test** system, and any scheme can be loaded from a CSV file today. Visa/JCB/Amex/UnionPay automatic intake needs their real formats. |
| "What if the merchant disagrees?" | Merchant evidence for chargebacks is handled by the admin team today; the merchant-facing evidence screen in MMS is not built. |

---

## Limits to be aware of

- **Simulated, not real.** JCB, Amex and UnionPay reason codes are placeholders.
- **Timing of the money.** A debit or credit is dated the day it is created and is folded into the settlement run **for that date**. If no settlement run is produced for that date, the adjustment waits. This is how all manual adjustments already behave.
- **Partial chargebacks.** The chargeback amount is the amount in the file's `transaction_amount` column.
- **Existing "recovery" code.** The older automatic recovery step in the settlement run builds its adjustment rows with column names that don't match the table; it looks broken (not run here). The new money rule deliberately bypasses it and marks debited cases as already deducted so nothing is debited twice. Finance/engineering should review that older step.
- **Turned off in production.** The simulator is disabled when the environment is production.