diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index d6b32d0f2..c9e3a7f45 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`. 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. @@ -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..c9e3a7f45 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`. 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. @@ -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..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 @@ -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 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