Simulate a card 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.

idstring required

The id of the card to simulate an authorization against.

Request body

amountinteger required

Authorization amount in the smallest unit of currency (e.g. cents for USD).

Example request

{
  "amount": 1250,
  "currency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$",
    "decimals": 2
  },
  "merchant": {
    "descriptor": "BLUE BOTTLE COFFEE SF",
    "mcc": "5814",
    "country": "US"
  }
}

Response

Simulated authorization processed. Returns the resulting card transaction.

idstring required

System-generated unique card transaction identifier

cardIdstring required

The id of the Card this transaction was made on.

issuerTransactionTokenstring

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.

accountIdstring required

Internal account id that funded this transaction (the funding source selected by Authorization Decisioning at auth time).

authorizedAtstring date-time required

When the auth was approved.

lastEventAtstring date-time

Timestamp of the most recent reconcile event (pull / clearing / refund) against this transaction.

createdAtstring date-time required

Creation timestamp (same as authorizedAt for card transactions).

updatedAtstring date-time required

Last update timestamp.

Example response

{
  "id": "CardTransaction:019542f5-b3e7-1d02-0000-000000000100",
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "issuerTransactionToken": "lithic_txn_b81c2a4f",
  "merchant": {
    "descriptor": "BLUE BOTTLE COFFEE SF",
    "mcc": "5814",
    "country": "US"
  },
  "authorizedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "settledAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "refundedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "pullSummary": {
    "count": 2,
    "totalAmount": 1500
  },
  "settlementSummary": {
    "count": 1,
    "totalAmount": 1500
  },
  "authorizedAt": "2026-05-08T14:30:00Z",
  "lastEventAt": "2026-05-08T15:42:11Z",
  "createdAt": "2026-05-08T14:30:00Z",
  "updatedAt": "2026-05-08T15:42:11Z"
}

v33

Simulate a card authorization

Path parameters

Request body

Example request

Response

Example response