---
title: "Simulate a card clearing"
method: POST
path: "/sandbox/cards/{id}/simulate/clearing"
tags: ["Sandbox"]
---

# Simulate a card clearing

`POST /sandbox/cards/{id}/simulate/clearing`

Simulate a clearing (settlement) event against an existing `CardTransaction` in the sandbox environment.

- A clearing `amount` greater than the authorized amount exercises the over-auth post-hoc-pull path (e.g. restaurant tip on top of a 20% over-auth).
- A clearing `amount` of `0` exercises the `AUTHORIZATION_EXPIRY` path — the auth expires with no clearing posted.
- Suffix-driven outcomes on the parent transaction's id govern whether the post-hoc pull succeeds (use the suffix table from `simulate/authorization` to construct deterministic test cases).

Production returns `404` on this path.

## Path parameters

- `id` string, required

## Request body

- SandboxCardClearingRequest — Sandbox-only request body for `POST /sandbox/cards/{id}/simulate/clearing`. Drives a clearing event against an existing `CardTransaction`. Pass an `amount` greater than the authorized amount to exercise the over-auth / restaurant-tip post-hoc-pull path; pass `0` to exercise `AUTHORIZATION_EXPIRY`. Suffix-driven outcomes on the parent transaction's id govern whether the post-hoc pull succeeds.
  - `cardTransactionId` string, required — The id of the `CardTransaction` to clear against. Must be in `AUTHORIZED` or `PARTIALLY_SETTLED` state.
  - `amount` integer, required — Clearing amount in the smallest unit of the transaction's currency. Set to `0` to simulate an authorization expiry with no clearing.

## Response `200`

Simulated clearing processed. Returns the updated card transaction.

- CardTransaction — Parent transaction row for a card authorization and all of the pulls / settlements / refunds that reconcile against it. Child events are rolled up into the `pullSummary`, `refundSummary`, and `settlementSummary` aggregates. Delivered as the payload of the generic transaction webhook stream (extends the Transaction model with a card destination type) on every transition.
  - `id` string, required — System-generated unique card transaction identifier
  - `cardId` string, required — The id of the `Card` this transaction was made on.
  - `issuerTransactionToken` string — Opaque identifier for the transaction on the underlying issuer. Used to cross-reference Grid records against issuer dashboards and webhooks.
  - `status` 'AUTHORIZED' | 'PARTIALLY_SETTLED' | 'SETTLED' | 'REFUNDED' | 'EXCEPTION', required — Lifecycle status of a card transaction. | Status | 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. | | `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. |
  - `merchant` CardMerchant, required
    - `descriptor` string, required — Merchant descriptor string captured from the card network at authorization time.
    - `mcc` string — Merchant Category Code (ISO 18245) — four-digit numeric string.
    - `country` string — Two-letter ISO 3166-1 alpha-2 country code of the merchant.
  - `authorizedAmount` CurrencyAmount, required
    - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
    - `currency` Currency, required
      - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
      - `name` string — Full name of the currency
      - `symbol` string — Symbol of the currency
      - `decimals` integer — Number of decimal places for the currency
  - `settledAmount` CurrencyAmount
    - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
    - `currency` Currency, required
      - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
      - `name` string — Full name of the currency
      - `symbol` string — Symbol of the currency
      - `decimals` integer — Number of decimal places for the currency
  - `refundedAmount` CurrencyAmount
    - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
    - `currency` Currency, required
      - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
      - `name` string — Full name of the currency
      - `symbol` string — Symbol of the currency
      - `decimals` integer — Number of decimal places for the currency
  - `accountId` string, required — Internal account id that funded this transaction (the funding source selected by Authorization Decisioning at auth time).
  - `pullSummary` CardPullSummary, required
    - `count` integer, required — Total number of pulls (debits) executed against the funding source for this transaction. `> 1` indicates one or more post-hoc pulls — e.g. restaurant tip / over-auth clearings.
    - `totalAmount` integer, required — Sum of all pull amounts in the smallest unit of the funding source's currency.
    - `pendingCount` integer — Number of pulls still in the `PENDING` state. Drops to zero when every pull has reached a terminal state. Non-zero values that persist beyond the expected settlement window are an early signal for the `EXCEPTION` path.
  - `refundSummary` CardRefundSummary, required
    - `count` integer, required — Number of refund (return) events received for this transaction.
    - `totalAmount` integer, required — Sum of all refund amounts in the smallest unit of the funding source's currency.
  - `settlementSummary` CardSettlementSummary, required
    - `count` integer, required — Number of settlement (clearing) events received for this transaction.
    - `totalAmount` integer, required — Sum of all settled amounts in the smallest unit of the funding source's currency.
  - `authorizedAt` string, date-time, required — When the auth was approved.
  - `lastEventAt` string, date-time — Timestamp of the most recent reconcile event (pull / clearing / refund) against this transaction.
  - `createdAt` string, date-time, required — Creation timestamp (same as `authorizedAt` for card transactions).
  - `updatedAt` string, date-time, required — Last update timestamp.

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized
- `403` — Forbidden - request was made with a production platform token
- `404` — Card or card transaction not found
- `500` — Internal service error

## Changes

- **2026-05-28** `d0bce562bffd` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/sandbox/cards/:id/simulate/clearing/post.md)

---

[API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/revisions/d0bce562bffd/schema)