docs(cards): drop the never-emitted REFUNDED card transaction status

mintlify/snippets/cards/implementation-overview.mdx

@@ -63,8 +63,9 @@ 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 does not
+change the status; it is reported in `refundedAmount`.
 
 The full event model is covered in
 [Reconciliation](/cards/transactions/reconciliation).

mintlify/snippets/cards/reconciliation.mdx

@@ -22,9 +22,7 @@ on the parent.
 ## Status transitions
 
 ```text
-              ┌─────────────────────────────────────┐
-              │                                     ▼
-AUTHORIZED ──► PARTIALLY_SETTLED ──► SETTLED ──► REFUNDED
+AUTHORIZED ──► PARTIALLY_SETTLED ──► SETTLED
               │
               └──► EXCEPTION  (pull failed after settlement)
 ```
@@ -33,8 +31,7 @@ AUTHORIZED ──► PARTIALLY_SETTLED ──► SETTLED ──► REFUNDED
 |--------|---------|
 | `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 merchant `RETURN` leaves the status here and reports 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 return keeps the parent `SETTLED`; the returned value accumulates in
+`refundedAmount`.
 
 ## End-to-end happy path
 

mintlify/snippets/cards/terminology.mdx

@@ -43,9 +43,8 @@ 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. The parent transaction stays
+`SETTLED`; the returned value accumulates in `refundedAmount`.
 
 ## Exception
 

openapi/components/schemas/cards/CardTransactionStatus.yaml

@@ -3,7 +3,6 @@ enum:
   - AUTHORIZED
   - PARTIALLY_SETTLED
   - SETTLED
-  - REFUNDED
   - EXCEPTION
 description: |
   Lifecycle status of a card transaction.
@@ -12,6 +11,5 @@ description: |
   |--------|-------------|
   | `AUTHORIZED` | The auth has been approved and a hold placed on the funding source; no clearing has arrived yet. |
   | `PARTIALLY_SETTLED` | At least one clearing has arrived and posted, but more clearings are still expected (split shipments, tips, multi-leg trips). |
-  | `SETTLED` | All clearings for the auth have posted and the transaction is closed against the funding source. |
-  | `REFUNDED` | A `RETURN` was received from the merchant; the net settled amount has been refunded in part or whole. |
+  | `SETTLED` | All clearings for the auth have posted and the transaction is closed against the funding source. A merchant `RETURN` does not change the status; the returned value is reported in `refundedAmount`. |
   | `EXCEPTION` | The transaction settled to the card network but the corresponding pull from the funding source failed (e.g. balance no longer covers the post-hoc clearing). Surfaces high-urgency alerts and is the dashboard query for stuck reconciliations. |

openapi/components/schemas/cards/SandboxCardReturnRequest.yaml

@@ -5,8 +5,8 @@ required:
 description: >-
   Sandbox-only request body for `POST /sandbox/cards/{id}/simulate/return`.
   Drives a `RETURN` event against an existing settled `CardTransaction`,
-  which creates a `CardRefund` and pushes the parent transaction towards
-  `REFUNDED` (full) or keeps it `SETTLED` (partial).
+  which creates a `CardRefund`. The parent stays `SETTLED`; the returned
+  value accumulates in `refundedAmount`.
 properties:
   cardTransactionId:
     type: string

openapi/components/schemas/webhooks/CardTransactionWebhook.yaml

@@ -12,5 +12,4 @@ allOf:
           - CARD_TRANSACTION.AUTHORIZED
           - CARD_TRANSACTION.PARTIALLY_SETTLED
           - CARD_TRANSACTION.SETTLED
-          - CARD_TRANSACTION.REFUNDED
           - CARD_TRANSACTION.EXCEPTION

openapi/components/schemas/webhooks/WebhookType.yaml

@@ -41,7 +41,6 @@ enum:
   - CARD_TRANSACTION.AUTHORIZED
   - CARD_TRANSACTION.PARTIALLY_SETTLED
   - CARD_TRANSACTION.SETTLED
-  - CARD_TRANSACTION.REFUNDED
   - CARD_TRANSACTION.EXCEPTION
   - WALLET_OPERATION.COMPLETED
   - WALLET_OPERATION.FAILED

openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return.yaml

@@ -3,8 +3,8 @@ post:
   description: >
     Simulate a merchant-initiated `RETURN` against an existing settled
     card transaction in the sandbox environment. Creates a `CardRefund` on
-    the parent and either flips the parent to `REFUNDED` (full refund) or
-    keeps it `SETTLED` with a non-zero `refundedAmount` (partial refund).
+    the parent; the parent stays `SETTLED` and the returned value
+    accumulates in `refundedAmount`.
 
 
     Production returns `404` on this path.

openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml

@@ -1,10 +1,13 @@
 post:
   summary: Simulate a card return reversal
   description: >
-    Simulate a `RETURN_REVERSAL` against an existing `REFUNDED` card
-    transaction in the sandbox environment — reversing a previously settled
-    return. The parent transaction must be in `REFUNDED` state. The resulting
-    card operation is delivered asynchronously via the issuer's events webhook.
+    Simulate a `RETURN_REVERSAL` against a card transaction with a posted
+    return in the sandbox environment — reversing a previously settled
+    return. The parent transaction must have a non-zero `refundedAmount`.
+    A successful reversal is netted off `refundedAmount` (a full reversal
+    brings it back to `0`) and the status stays `SETTLED`. The resulting
+    card operation is delivered asynchronously via the issuer's events
+    webhook.
 
 
     Note: authorization reversal / void has no dedicated card-issuer simulate