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 response = await client.sandbox.cards.simulate.clearing(
  'Card:019542f5-b3e7-1d02-0000-000000000010',
  { amount: 1500, cardTransactionId: 'CardTransaction:019542f5-b3e7-1d02-0000-000000000100' },
);

console.log(response.issuerTransactionToken);

package com.lightspark.grid.example

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

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 response: SimulateClearingResponse = client.sandbox().cards().simulate().clearing(params)
}

{
  "issuerTransactionToken": "f3a1c2d4-5b6e-7890-abcd-ef0123456789"
}

{
  "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 response = await client.sandbox.cards.simulate.clearing(
  'Card:019542f5-b3e7-1d02-0000-000000000010',
  { amount: 1500, cardTransactionId: 'CardTransaction:019542f5-b3e7-1d02-0000-000000000100' },
);

console.log(response.issuerTransactionToken);

package com.lightspark.grid.example

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

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 response: SimulateClearingResponse = client.sandbox().cards().simulate().clearing(params)
}

{
  "issuerTransactionToken": "f3a1c2d4-5b6e-7890-abcd-ef0123456789"
}

{
  "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

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.

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.

Example:

"f3a1c2d4-5b6e-7890-abcd-ef0123456789"

Simulate a card authorization

Simulate a card return

⌘I

Using the API

API documentation

Simulate a card clearing

Authorizations

Path Parameters

Body

Response