From 1d3667d8402ae30a9c36151303ffc2c61a469f93 Mon Sep 17 00:00:00 2001 From: Aaryaman Bhute Date: Fri, 4 Sep 2026 23:47:06 -0700 Subject: [PATCH 1/2] docs(cards): drop the never-emitted REFUNDED card transaction status Grid stopped deriving REFUNDED for card transactions in webdev#30710 (2026-07-20): a merchant return leaves the transaction SETTLED and reports the returned value in refundedAmount. The server enum, the status derivation, and the webhook type mapper have not carried REFUNDED since, so the published CardTransactionStatus value, the CARD_TRANSACTION.REFUNDED webhook type, and the sandbox return / return-reversal descriptions documented a transition that never fires. Remove the value and the webhook type, reword the return simulators and the card docs snippets around refundedAmount, and turn the webhook example for a returned purchase into a SETTLED delivery. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01EvF4PtTuGgETX8vFnsYEjQ --- mintlify/openapi.yaml | 20 ++++++++----------- .../cards/implementation-overview.mdx | 5 +++-- mintlify/snippets/cards/reconciliation.mdx | 7 ++----- mintlify/snippets/cards/sandbox-testing.mdx | 4 ++-- mintlify/snippets/cards/terminology.mdx | 5 ++--- openapi.yaml | 20 ++++++++----------- .../schemas/cards/CardTransactionStatus.yaml | 4 +--- .../cards/SandboxCardReturnRequest.yaml | 4 ++-- .../webhooks/CardTransactionWebhook.yaml | 1 - .../schemas/webhooks/WebhookType.yaml | 1 - .../sandbox_cards_{id}_simulate_return.yaml | 4 ++-- ...x_cards_{id}_simulate_return_reversal.yaml | 9 +++++---- openapi/webhooks/card-transaction.yaml | 11 +++++----- 13 files changed, 41 insertions(+), 54 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index d6b32d0f2..f4aededc1 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -9083,7 +9083,7 @@ paths: post: summary: Simulate a card return 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). + Simulate a merchant-initiated `RETURN` against an existing settled card transaction in the sandbox environment. Creates a `CardRefund` on the parent; the parent stays `SETTLED` and the returned value accumulates in `refundedAmount`. Production returns `404` on this path. operationId: sandboxSimulateCardReturn @@ -9596,7 +9596,7 @@ paths: 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`. The resulting card operation is delivered asynchronously via the issuer's events webhook. Note: authorization reversal / void has no dedicated card-issuer simulate path (the void simulator emits a distinct `VOID` event), so — like authorization expiry — it is not exposed here. @@ -11681,7 +11681,7 @@ webhooks: post: summary: Card transaction description: | - Webhook that is called on every state transition of a card `CardTransaction`. Fires when an authorization is approved (`CARD_TRANSACTION.AUTHORIZED`), as clearings settle against it (`CARD_TRANSACTION.PARTIALLY_SETTLED`, `CARD_TRANSACTION.SETTLED`), when settled funds are returned (`CARD_TRANSACTION.REFUNDED`), and when a pull or confirmation fails (`CARD_TRANSACTION.EXCEPTION`). The payload carries the full `CardTransaction` resource. + Webhook that is called on every state transition of a card `CardTransaction`. Fires when an authorization is approved (`CARD_TRANSACTION.AUTHORIZED`), as clearings settle against it (`CARD_TRANSACTION.PARTIALLY_SETTLED`, `CARD_TRANSACTION.SETTLED`), and when a pull or confirmation fails (`CARD_TRANSACTION.EXCEPTION`). A merchant return does not change the status: the webhook fires again for the current status with the returned value in `refundedAmount`. The payload carries the full `CardTransaction` resource. This endpoint should be implemented by clients of the Grid API. @@ -11796,10 +11796,10 @@ webhooks: createdAt: '2026-05-09T10:00:00Z' updatedAt: '2026-05-09T15:42:11Z' refunded: - summary: Settled funds returned by the merchant + summary: Settled funds returned by the merchant (status stays SETTLED) value: id: Webhook:019542f5-b3e7-1d02-0000-000000000042 - type: CARD_TRANSACTION.REFUNDED + type: CARD_TRANSACTION.SETTLED timestamp: '2026-05-10T09:15:00Z' data: type: CARD @@ -11808,7 +11808,7 @@ webhooks: customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 issuerTransactionToken: lithic_txn_b81c2a4f - status: REFUNDED + status: SETTLED direction: DEBIT merchant: descriptor: BLUE BOTTLE COFFEE SF @@ -23607,7 +23607,6 @@ components: - AUTHORIZED - PARTIALLY_SETTLED - SETTLED - - REFUNDED - EXCEPTION description: | Lifecycle status of a card transaction. @@ -23616,8 +23615,7 @@ components: |--------|-------------| | `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. | CardMerchant: type: object @@ -26239,7 +26237,7 @@ components: required: - cardTransactionId - amount - 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). + 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`. The parent stays `SETTLED`; the returned value accumulates in `refundedAmount`. properties: cardTransactionId: type: string @@ -27087,7 +27085,6 @@ components: - CARD_TRANSACTION.AUTHORIZED - CARD_TRANSACTION.PARTIALLY_SETTLED - CARD_TRANSACTION.SETTLED - - CARD_TRANSACTION.REFUNDED - CARD_TRANSACTION.EXCEPTION - WALLET_OPERATION.COMPLETED - WALLET_OPERATION.FAILED @@ -27345,7 +27342,6 @@ components: - CARD_TRANSACTION.AUTHORIZED - CARD_TRANSACTION.PARTIALLY_SETTLED - CARD_TRANSACTION.SETTLED - - CARD_TRANSACTION.REFUNDED - CARD_TRANSACTION.EXCEPTION WalletOperationCompletedData: title: Wallet Operation Completed Data diff --git a/mintlify/snippets/cards/implementation-overview.mdx b/mintlify/snippets/cards/implementation-overview.mdx index 03c878896..4293ef831 100644 --- a/mintlify/snippets/cards/implementation-overview.mdx +++ b/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). diff --git a/mintlify/snippets/cards/reconciliation.mdx b/mintlify/snippets/cards/reconciliation.mdx index bb4e3b4c4..0ef616924 100644 --- a/mintlify/snippets/cards/reconciliation.mdx +++ b/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 diff --git a/mintlify/snippets/cards/sandbox-testing.mdx b/mintlify/snippets/cards/sandbox-testing.mdx index d9c175c15..75d408810 100644 --- a/mintlify/snippets/cards/sandbox-testing.mdx +++ b/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 diff --git a/mintlify/snippets/cards/terminology.mdx b/mintlify/snippets/cards/terminology.mdx index 33db0624e..888ce47a7 100644 --- a/mintlify/snippets/cards/terminology.mdx +++ b/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 diff --git a/openapi.yaml b/openapi.yaml index d6b32d0f2..f4aededc1 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9083,7 +9083,7 @@ paths: post: summary: Simulate a card return 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). + Simulate a merchant-initiated `RETURN` against an existing settled card transaction in the sandbox environment. Creates a `CardRefund` on the parent; the parent stays `SETTLED` and the returned value accumulates in `refundedAmount`. Production returns `404` on this path. operationId: sandboxSimulateCardReturn @@ -9596,7 +9596,7 @@ paths: 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`. The resulting card operation is delivered asynchronously via the issuer's events webhook. Note: authorization reversal / void has no dedicated card-issuer simulate path (the void simulator emits a distinct `VOID` event), so — like authorization expiry — it is not exposed here. @@ -11681,7 +11681,7 @@ webhooks: post: summary: Card transaction description: | - Webhook that is called on every state transition of a card `CardTransaction`. Fires when an authorization is approved (`CARD_TRANSACTION.AUTHORIZED`), as clearings settle against it (`CARD_TRANSACTION.PARTIALLY_SETTLED`, `CARD_TRANSACTION.SETTLED`), when settled funds are returned (`CARD_TRANSACTION.REFUNDED`), and when a pull or confirmation fails (`CARD_TRANSACTION.EXCEPTION`). The payload carries the full `CardTransaction` resource. + Webhook that is called on every state transition of a card `CardTransaction`. Fires when an authorization is approved (`CARD_TRANSACTION.AUTHORIZED`), as clearings settle against it (`CARD_TRANSACTION.PARTIALLY_SETTLED`, `CARD_TRANSACTION.SETTLED`), and when a pull or confirmation fails (`CARD_TRANSACTION.EXCEPTION`). A merchant return does not change the status: the webhook fires again for the current status with the returned value in `refundedAmount`. The payload carries the full `CardTransaction` resource. This endpoint should be implemented by clients of the Grid API. @@ -11796,10 +11796,10 @@ webhooks: createdAt: '2026-05-09T10:00:00Z' updatedAt: '2026-05-09T15:42:11Z' refunded: - summary: Settled funds returned by the merchant + summary: Settled funds returned by the merchant (status stays SETTLED) value: id: Webhook:019542f5-b3e7-1d02-0000-000000000042 - type: CARD_TRANSACTION.REFUNDED + type: CARD_TRANSACTION.SETTLED timestamp: '2026-05-10T09:15:00Z' data: type: CARD @@ -11808,7 +11808,7 @@ webhooks: customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 issuerTransactionToken: lithic_txn_b81c2a4f - status: REFUNDED + status: SETTLED direction: DEBIT merchant: descriptor: BLUE BOTTLE COFFEE SF @@ -23607,7 +23607,6 @@ components: - AUTHORIZED - PARTIALLY_SETTLED - SETTLED - - REFUNDED - EXCEPTION description: | Lifecycle status of a card transaction. @@ -23616,8 +23615,7 @@ components: |--------|-------------| | `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. | CardMerchant: type: object @@ -26239,7 +26237,7 @@ components: required: - cardTransactionId - amount - 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). + 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`. The parent stays `SETTLED`; the returned value accumulates in `refundedAmount`. properties: cardTransactionId: type: string @@ -27087,7 +27085,6 @@ components: - CARD_TRANSACTION.AUTHORIZED - CARD_TRANSACTION.PARTIALLY_SETTLED - CARD_TRANSACTION.SETTLED - - CARD_TRANSACTION.REFUNDED - CARD_TRANSACTION.EXCEPTION - WALLET_OPERATION.COMPLETED - WALLET_OPERATION.FAILED @@ -27345,7 +27342,6 @@ components: - CARD_TRANSACTION.AUTHORIZED - CARD_TRANSACTION.PARTIALLY_SETTLED - CARD_TRANSACTION.SETTLED - - CARD_TRANSACTION.REFUNDED - CARD_TRANSACTION.EXCEPTION WalletOperationCompletedData: title: Wallet Operation Completed Data diff --git a/openapi/components/schemas/cards/CardTransactionStatus.yaml b/openapi/components/schemas/cards/CardTransactionStatus.yaml index 01be9d92c..0c45c1ac8 100644 --- a/openapi/components/schemas/cards/CardTransactionStatus.yaml +++ b/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. | diff --git a/openapi/components/schemas/cards/SandboxCardReturnRequest.yaml b/openapi/components/schemas/cards/SandboxCardReturnRequest.yaml index e64a99795..746d63ff2 100644 --- a/openapi/components/schemas/cards/SandboxCardReturnRequest.yaml +++ b/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 diff --git a/openapi/components/schemas/webhooks/CardTransactionWebhook.yaml b/openapi/components/schemas/webhooks/CardTransactionWebhook.yaml index 0d46e69d5..ef083d799 100644 --- a/openapi/components/schemas/webhooks/CardTransactionWebhook.yaml +++ b/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 diff --git a/openapi/components/schemas/webhooks/WebhookType.yaml b/openapi/components/schemas/webhooks/WebhookType.yaml index 0d7da939d..c16199b7d 100644 --- a/openapi/components/schemas/webhooks/WebhookType.yaml +++ b/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 diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return.yaml index 195fd41c9..56e205fcf 100644 --- a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return.yaml +++ b/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. diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml index 030d87076..486d896a6 100644 --- a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml +++ b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml @@ -1,10 +1,11 @@ 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`. + The resulting card operation is delivered asynchronously via the + issuer's events webhook. Note: authorization reversal / void has no dedicated card-issuer simulate diff --git a/openapi/webhooks/card-transaction.yaml b/openapi/webhooks/card-transaction.yaml index 5a9a054bb..f6f18178c 100644 --- a/openapi/webhooks/card-transaction.yaml +++ b/openapi/webhooks/card-transaction.yaml @@ -5,8 +5,9 @@ post: `CardTransaction`. Fires when an authorization is approved (`CARD_TRANSACTION.AUTHORIZED`), as clearings settle against it (`CARD_TRANSACTION.PARTIALLY_SETTLED`, `CARD_TRANSACTION.SETTLED`), - when settled funds are returned (`CARD_TRANSACTION.REFUNDED`), and - when a pull or confirmation fails (`CARD_TRANSACTION.EXCEPTION`). + and when a pull or confirmation fails (`CARD_TRANSACTION.EXCEPTION`). + A merchant return does not change the status: the webhook fires again + for the current status with the returned value in `refundedAmount`. The payload carries the full `CardTransaction` resource. @@ -133,10 +134,10 @@ post: createdAt: '2026-05-09T10:00:00Z' updatedAt: '2026-05-09T15:42:11Z' refunded: - summary: Settled funds returned by the merchant + summary: Settled funds returned by the merchant (status stays SETTLED) value: id: Webhook:019542f5-b3e7-1d02-0000-000000000042 - type: CARD_TRANSACTION.REFUNDED + type: CARD_TRANSACTION.SETTLED timestamp: '2026-05-10T09:15:00Z' data: type: CARD @@ -145,7 +146,7 @@ post: customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 issuerTransactionToken: lithic_txn_b81c2a4f - status: REFUNDED + status: SETTLED direction: DEBIT merchant: descriptor: BLUE BOTTLE COFFEE SF From df80ffbd509153a20744a61c8d3ff73f68988c3e Mon Sep 17 00:00:00 2001 From: Aaryaman Bhute Date: Sat, 5 Sep 2026 00:55:06 -0700 Subject: [PATCH 2/2] docs(cards): say what a return reversal does to refundedAmount A successful reversal is netted off refundedAmount (a full reversal brings it back to 0) and the status stays SETTLED, matching the server's returns-minus-reversals derivation. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01EvF4PtTuGgETX8vFnsYEjQ --- mintlify/openapi.yaml | 2 +- openapi.yaml | 2 +- .../cards/sandbox_cards_{id}_simulate_return_reversal.yaml | 6 ++++-- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index f4aededc1..c9e3a7f45 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -9596,7 +9596,7 @@ paths: post: summary: Simulate a card return reversal description: | - 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`. 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 path (the void simulator emits a distinct `VOID` event), so — like authorization expiry — it is not exposed here. diff --git a/openapi.yaml b/openapi.yaml index f4aededc1..c9e3a7f45 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9596,7 +9596,7 @@ paths: post: summary: Simulate a card return reversal description: | - 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`. 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 path (the void simulator emits a distinct `VOID` event), so — like authorization expiry — it is not exposed here. diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml index 486d896a6..2d2c57c71 100644 --- a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml +++ b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml @@ -4,8 +4,10 @@ post: 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`. - The resulting card operation is delivered asynchronously via the - issuer's events webhook. + 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