Skip to main content
POST
/
sandbox
/
cards
/
{id}
/
simulate
/
clearing
cURL
curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/sandbox/cards/{id}/simulate/clearing \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cardTransactionId": "CardTransaction:019542f5-b3e7-1d02-0000-000000000100",
  "amount": 1500
}
'
{
  "id": "CardTransaction:019542f5-b3e7-1d02-0000-000000000100",
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "merchant": {
    "descriptor": "BLUE BOTTLE COFFEE SF",
    "mcc": "5814",
    "country": "US"
  },
  "authorizedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "pullSummary": {
    "count": 2,
    "totalAmount": 1500,
    "pendingCount": 0
  },
  "refundSummary": {
    "count": 0,
    "totalAmount": 0
  },
  "settlementSummary": {
    "count": 1,
    "totalAmount": 1500
  },
  "authorizedAt": "2026-05-08T14:30:00Z",
  "createdAt": "2026-05-08T14:30:00Z",
  "updatedAt": "2026-05-08T15:42:11Z",
  "issuerTransactionToken": "lithic_txn_b81c2a4f",
  "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
    }
  },
  "lastEventAt": "2026-05-08T15:42:11Z"
}

Documentation Index

Fetch the complete documentation index at: https://grid.lightspark.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

API token authentication using format <api token id>:<api client secret>

Path Parameters

​
id
string
required

The id of the card the clearing applies to.

Body

application/json

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.

Example:

"CardTransaction:019542f5-b3e7-1d02-0000-000000000100"

​
amount
integer<int64>
required

Clearing amount in the smallest unit of the transaction's currency. Set to 0 to simulate an authorization expiry with no clearing.

Required range: x >= 0
Example:

1500

Response

Simulated clearing processed. Returns the updated card transaction.

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
read-only

System-generated unique card transaction identifier

Example:

"CardTransaction:019542f5-b3e7-1d02-0000-000000000100"

​
cardId
string
required

The id of the Card this transaction was made on.

Example:

"Card:019542f5-b3e7-1d02-0000-000000000010"

​
status
enum<string>
required

Lifecycle status of a card transaction.

StatusDescription
AUTHORIZEDThe auth has been approved and a hold placed on the funding source; no clearing has arrived yet.
PARTIALLY_SETTLEDAt least one clearing has arrived and posted, but more clearings are still expected (split shipments, tips, multi-leg trips).
SETTLEDAll clearings for the auth have posted and the transaction is closed against the funding source.
REFUNDEDA RETURN was received from the merchant; the net settled amount has been refunded in part or whole.
EXCEPTIONThe 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.
Available options:
AUTHORIZED,
PARTIALLY_SETTLED,
SETTLED,
REFUNDED,
EXCEPTION
​
merchant
object
required
​
authorizedAmount
object
required
​
accountId
string
required

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

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"

​
pullSummary
object
required
​
refundSummary
object
required
​
settlementSummary
object
required
​
authorizedAt
string<date-time>
required

When the auth was approved.

Example:

"2026-05-08T14:30:00Z"

​
createdAt
string<date-time>
required
read-only

Creation timestamp (same as authorizedAt for card transactions).

Example:

"2026-05-08T14:30:00Z"

​
updatedAt
string<date-time>
required
read-only

Last update timestamp.

Example:

"2026-05-08T15:42:11Z"

​
issuerTransactionToken
string
read-only

Opaque identifier for the transaction on the underlying issuer. Used to cross-reference Grid records against issuer dashboards and webhooks.

Example:

"lithic_txn_b81c2a4f"

​
settledAmount
object
​
refundedAmount
object
​
lastEventAt
string<date-time>

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

Example:

"2026-05-08T15:42:11Z"