remove the REFUNDED card transaction status from the spec

mintlify/changelog.mdx

@@ -11,6 +11,27 @@ changes and roadmap, [book a live demo](https://www.lightspark.com/contact) or
 
 <Update label="September 2026">
 
+## Card returns report as `SETTLED` with a `refundedAmount`
+
+`REFUNDED` is removed from `CardTransactionStatus`, and `CARD_TRANSACTION.REFUNDED` from
+the webhook types. A card transaction's status tracks settlement only—a return is
+reported through `direction` and `refundedAmount`, which together already carry it.
+
+- A settled purchase that the merchant later returns stays `SETTLED`, with the returned
+  value in `refundedAmount`. A standalone merchant refund arrives as `direction: CREDIT`
+  and `status: SETTLED`, with the credited value in `settledAmount`.
+- Returns no longer get a webhook type of their own—the transaction re-fires
+  `CARD_TRANSACTION.SETTLED` with the updated amounts.
+- The sandbox return reversal simulator requires a parent with a posted return (non-zero
+  `refundedAmount`) rather than a `REFUNDED` parent, which the previous docs described
+  and the server never produced.
+
+Nothing you have received changes: the status was always derived on read, so existing
+transactions already report `SETTLED`. `TransactionStatus.REFUNDED` on cross-border
+payments is a separate enum and is unaffected.
+
+See [Reconciliation](/cards/transactions/reconciliation).
+
 ## Sandbox KYC and KYB follow the production flow
 
 Unregulated sandbox platforms now resolve a customer's verification from a submitted

mintlify/snippets/cards/implementation-overview.mdx

@@ -63,8 +63,10 @@ Each authorization on a card produces a parent `CardTransaction` row.
 Children (pulls, clearings, refunds) are reconciled against the parent
 and rolled up into `pullSummary`, `settlementSummary`, and
 `refundSummary` aggregates. The lifecycle status moves
-`AUTHORIZED → PARTIALLY_SETTLED → SETTLED → REFUNDED`, with
-`EXCEPTION` as the failure path for stuck post-hoc pulls.
+`AUTHORIZED → PARTIALLY_SETTLED → SETTLED`, with `EXCEPTION` as the
+failure path for stuck post-hoc pulls. A merchant return keeps the
+transaction `SETTLED` and reports the returned value in
+`refundedAmount`.
 
 The full event model is covered in
 [Reconciliation](/cards/transactions/reconciliation).

mintlify/snippets/cards/reconciliation.mdx

@@ -22,19 +22,19 @@ on the parent.
 ## Status transitions
 
 ```text
-              ┌─────────────────────────────────────┐
-              │                                     ▼
-AUTHORIZED ──► PARTIALLY_SETTLED ──► SETTLED ──► REFUNDED
+AUTHORIZED ──► PARTIALLY_SETTLED ──► SETTLED
               │
               └──► EXCEPTION  (pull failed after settlement)
 ```
 
+A merchant `RETURN` does not move the status. The transaction stays
+`SETTLED` and the returned value appears in `refundedAmount`.
+
 | Status | Meaning |
 |--------|---------|
 | `AUTHORIZED` | Auth approved, hold placed, no clearings yet. |
 | `PARTIALLY_SETTLED` | At least one clearing landed, but more are still expected (split shipments, multi-leg trips). |
-| `SETTLED` | All clearings for the auth have posted. The transaction is closed against the funding source. |
-| `REFUNDED` | A `RETURN` was received and the net settled amount has been refunded in full or part. |
+| `SETTLED` | All clearings for the auth have posted. The transaction is closed against the funding source. A `RETURN` received afterwards keeps it `SETTLED` with the returned value in `refundedAmount`. |
 | `EXCEPTION` | The transaction settled to the network but the corresponding pull from the funding source failed. |
 
 Every transition is delivered via the generic transaction webhook

mintlify/snippets/cards/sandbox-testing.mdx

@@ -100,8 +100,8 @@ curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-00000000
   }'
 ```
 
-A full refund flips the parent to `REFUNDED`; a partial refund keeps
-it `SETTLED` with a non-zero `refundedAmount`.
+A refund keeps the parent `SETTLED` with a non-zero `refundedAmount`,
+whether it is full or partial.
 
 ## End-to-end happy path
 

mintlify/snippets/cards/terminology.mdx

@@ -43,9 +43,9 @@ land.
 ## Refund
 
 A merchant-initiated `RETURN` against a settled transaction. Refunds
-flow back to the funding source. A full refund moves the parent
-transaction to `REFUNDED`; a partial refund keeps it `SETTLED` with a
-non-zero `refundedAmount`.
+flow back to the funding source. A refund keeps the parent transaction
+`SETTLED` and reports the returned value in `refundedAmount`, whether
+it is full or partial.
 
 ## Exception