---
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 shared by the card authorization-family simulate endpoints: `simulate/authorization`, `simulate/credit_authorization`, `simulate/financial_authorization`, `simulate/financial_credit_authorization`, and `simulate/credit_authorization_advice`. 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 `simulate/authorization` 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 `202`

Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event.

- SandboxCardSimulationResponse — Response body for the sandbox card-event simulators. The simulate call pokes the card issuer's sandbox; the resulting card operation is delivered asynchronously via the issuer's events webhook, never synchronously in this response.
  - `issuerTransactionToken` string, required — The card issuer's transaction token for the simulated event. Correlates the eventual webhook-delivered card operation back to this simulate call.

## 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

---

[API](https://skmtc.net/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.net/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stainless-api/grid-api/versions/526036c12609/schema)