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
}
'

import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const cardTransaction = await client.sandbox.cards.simulate.clearing(
  'Card:019542f5-b3e7-1d02-0000-000000000010',
  { amount: 1500, cardTransactionId: 'CardTransaction:019542f5-b3e7-1d02-0000-000000000100' },
);

console.log(cardTransaction.id);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.cards.CardTransaction
import com.lightspark.grid.models.sandbox.cards.simulate.ClearingRequest
import com.lightspark.grid.models.sandbox.cards.simulate.SimulateClearingParams

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: SimulateClearingParams = SimulateClearingParams.builder()
        .id("Card:019542f5-b3e7-1d02-0000-000000000010")
        .clearingRequest(ClearingRequest.builder()
            .amount(1500L)
            .cardTransactionId("CardTransaction:019542f5-b3e7-1d02-0000-000000000100")
            .build())
        .build()
    val cardTransaction: CardTransaction = client.sandbox().cards().simulate().clearing(params)
}

{
  "type": "CARD",
  "id": "CardTransaction:019542f5-b3e7-1d02-0000-000000000100",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCustomerId": "18d3e5f7b4a9c2",
  "direction": "DEBIT",
  "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",
  "authorizedAt": "2026-05-08T14:30:00Z",
  "createdAt": "2026-05-08T14:30:00Z",
  "updatedAt": "2026-05-08T15:42:11Z",
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "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
    }
  },
  "pullSummary": {
    "count": 2,
    "totalAmount": 1500,
    "pendingCount": 0
  },
  "refundSummary": {
    "count": 0,
    "totalAmount": 0
  },
  "settlementSummary": {
    "count": 1,
    "totalAmount": 1500
  },
  "lastEventAt": "2026-05-08T15:42:11Z"
}

{
  "status": 400,
  "message": "<string>",
  "details": {}
}

{
  "status": 401,
  "message": "<string>",
  "details": {}
}

{
  "status": 403,
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "message": "<string>",
  "details": {}
}

Sandbox

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

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
}
'

import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const cardTransaction = await client.sandbox.cards.simulate.clearing(
  'Card:019542f5-b3e7-1d02-0000-000000000010',
  { amount: 1500, cardTransactionId: 'CardTransaction:019542f5-b3e7-1d02-0000-000000000100' },
);

console.log(cardTransaction.id);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.cards.CardTransaction
import com.lightspark.grid.models.sandbox.cards.simulate.ClearingRequest
import com.lightspark.grid.models.sandbox.cards.simulate.SimulateClearingParams

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: SimulateClearingParams = SimulateClearingParams.builder()
        .id("Card:019542f5-b3e7-1d02-0000-000000000010")
        .clearingRequest(ClearingRequest.builder()
            .amount(1500L)
            .cardTransactionId("CardTransaction:019542f5-b3e7-1d02-0000-000000000100")
            .build())
        .build()
    val cardTransaction: CardTransaction = client.sandbox().cards().simulate().clearing(params)
}

{
  "type": "CARD",
  "id": "CardTransaction:019542f5-b3e7-1d02-0000-000000000100",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCustomerId": "18d3e5f7b4a9c2",
  "direction": "DEBIT",
  "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",
  "authorizedAt": "2026-05-08T14:30:00Z",
  "createdAt": "2026-05-08T14:30:00Z",
  "updatedAt": "2026-05-08T15:42:11Z",
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "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
    }
  },
  "pullSummary": {
    "count": 2,
    "totalAmount": 1500,
    "pendingCount": 0
  },
  "refundSummary": {
    "count": 0,
    "totalAmount": 0
  },
  "settlementSummary": {
    "count": 1,
    "totalAmount": 1500
  },
  "lastEventAt": "2026-05-08T15:42:11Z"
}

{
  "status": 400,
  "message": "<string>",
  "details": {}
}

{
  "status": 401,
  "message": "<string>",
  "details": {}
}

{
  "status": 403,
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

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

Path Parameters

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.

type

enum<string>

required

Discriminator identifying this transaction as a card transaction in the Transaction list.

Available options:

CARD

string

required

read-only

System-generated unique card transaction identifier

Example:

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

customerId

string

required

System ID of the customer (cardholder) this transaction belongs to.

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

platformCustomerId

string

required

Platform-specific ID of the customer (cardholder) this transaction belongs to.

Example:

"18d3e5f7b4a9c2"

status

enum<string>

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.

Available options:

AUTHORIZED,

PARTIALLY_SETTLED,

SETTLED,

REFUNDED,

EXCEPTION

direction

enum<string>

required

Card transactions debit the customer's account.

Available options:

CREDIT,

DEBIT

Example:

"DEBIT"

merchant

object

required

Show child attributes

authorizedAmount

object

required

Show child attributes

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"

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"

cardId

string

The id of the Card this transaction was made on.

Example:

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

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

Show child attributes

refundedAmount

object

Show child attributes

pullSummary

object

Show child attributes

refundSummary

object

Show child attributes

settlementSummary

object

Show child attributes

lastEventAt

string<date-time>

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

Example:

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

Simulate a card authorization

Simulate a card return

⌘I

Using the API

API documentation

Simulate a card clearing

Authorizations

Path Parameters

Body

Response