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.

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

cURL

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/sandbox/cards/{id}/simulate/authorization \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 1250,
  "currency": {
    "code": "USD"
  },
  "merchant": {
    "descriptor": "BLUE BOTTLE COFFEE SF",
    "mcc": "5814",
    "country": "US"
  }
}
'

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.authorization(
  'Card:019542f5-b3e7-1d02-0000-000000000010',
  {
    amount: 1250,
    currency: { code: 'USD' },
    merchant: {
      descriptor: 'BLUE BOTTLE COFFEE SF',
      mcc: '5814',
      country: 'US',
    },
  },
);

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.quotes.Currency
import com.lightspark.grid.models.sandbox.cards.simulate.AuthorizationRequest
import com.lightspark.grid.models.sandbox.cards.simulate.CardMerchant
import com.lightspark.grid.models.sandbox.cards.simulate.SimulateAuthorizationParams
import com.lightspark.grid.models.sandbox.cards.simulate.SimulateAuthorizationResponse

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

    val params: SimulateAuthorizationParams = SimulateAuthorizationParams.builder()
        .id("Card:019542f5-b3e7-1d02-0000-000000000010")
        .authorizationRequest(AuthorizationRequest.builder()
            .amount(1250L)
            .currency(Currency.builder().build())
            .merchant(CardMerchant.builder()
                .descriptor("BLUE BOTTLE COFFEE SF")
                .build())
            .build())
        .build()
    val response: SimulateAuthorizationResponse = client.sandbox().cards().simulate().authorization(params)
}

202

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

id · string · required

The id of the card to simulate an authorization against.

Body

application/json

Sandbox-only request body shared by the card authorization-family simulate endpoints: simulate/authorization, simulate/credit_authorization, simulate/financial_authorization, simulate/financial_credit_authorization, and simulate/credit_authorization_advice. Drives the same internal authorization + reconcile paths that the issuer would call in production. The decisioning outcome is controlled by the last three characters of merchant.descriptor — see the simulate/authorization documentation for the suffix table.

amount · integer<int64> · required

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

Example:

1250

currency · object · required

Show child attributes

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"