Simulate a card balance inquiry

Simulate a balance-inquiry authorization against a card in the sandbox environment. A balance inquiry is always a 0-amount authorization, so the request carries no amount — only the merchant. Drives the same internal paths the card issuer would call in production. The resulting card operation is delivered asynchronously via the issuer’s events webhook.

Production returns 404 on this path.

POST /sandbox/cards/{id}/simulate/balance_inquiry

Simulate a card balance inquiry

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/sandbox/cards/{id}/simulate/balance_inquiry \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "merchant": {
    "descriptor": "SHELL OIL 12345678",
    "mcc": "5541",
    "country": "US"
  }
}
'

202

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

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 to simulate a balance inquiry against.

Body

application/json

Sandbox-only request body for POST /sandbox/cards/{id}/simulate/balance_inquiry. Drives a balance-inquiry authorization against the card. A balance inquiry is always a 0-amount authorization, so it carries no amount.

merchant · object · required

Show child attributes

Response

202

application/json

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"