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

# Simulate a card authorization

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

Simulate an inbound card authorization in the sandbox environment. Drives the same internal `authorize` + `reconcile` paths the card issuer would call in production, so platforms can exercise Grid's decisioning + funding-source pull behavior end-to-end without an external network round-trip.

The decisioning outcome is controlled by the last three characters of `merchant.descriptor`:

| Suffix | Outcome | | ------ | ------- | | `002`  | Decline — `INSUFFICIENT_FUNDS` (the pull on the funding source fails) | | `003`  | Decline — `CARD_PAUSED` (intended to verify a frozen card refuses auths) | | `005`  | Delayed pull (~30s) — exercises the `PENDING → CONFIRMED` path | | `006`  | Pull succeeds but the confirmation event reports `FAILED` — exercises the high-urgency `EXCEPTION` alert | | any other | Approved |

Production returns `404` on this path.

## Path parameters

- `id` string, required

## Request body

- SandboxCardAuthorizationRequest — Sandbox-only request body for `POST /sandbox/cards/{id}/simulate/authorization`. Drives the same internal authorization + reconcile paths that the issuer would call in production. The decisioning outcome is controlled by the last three characters of `merchant.descriptor` — see the endpoint documentation for the suffix table.
  - `amount` integer, required — Authorization amount in the smallest unit of `currency` (e.g. cents for USD).
  - `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
  - `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.

## Response `200`

Simulated authorization processed. Returns the resulting 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 not found (also returned in production for this path)
- `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/authorization/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)