Sandbox

Simulate a card authorization

Changed on

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 | Declined, cardDeclinedReason: INSUFFICIENT_FUNDS. Sandbox only: production approves an underfunded authorization and resolves it as EXCEPTION when the pull fails | | 003 | Declined, cardDeclinedReason: CARD_NOT_ACTIVE. Use against a FROZEN card to verify it refuses authorizations | | 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 |

merchant.descriptor must be 1–25 characters — the width of the card network's acceptor-name field. A longer one is rejected with 400 INVALID_INPUT.

Production returns 404 on this path.

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

Request

  • Base URL: https://api.lightspark.com/grid/2025-10-13
  • URL: https://api.lightspark.com/grid/2025-10-13/sandbox/cards/{id}/simulate/authorization
  • Auth: HTTP basic

Path parameters

idstring required

The id of the card to simulate an authorization against.

Request body

amountinteger required

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

Example request

{
  "amount": 1250,
  "currency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$",
    "decimals": 2
  },
  "merchant": {
    "descriptor": "BLUE BOTTLE COFFEE SF",
    "mcc": "5814",
    "city": "San Francisco",
    "state": "CA",
    "country": "US"
  }
}

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.

issuerTransactionTokenstring required

The card issuer's transaction token for the simulated event. Correlates the eventual webhook-delivered card operation back to this simulate call.

Example response

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

Changes

  • 3966e5d38aadRevision changes
    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • warning

      added the new ACCOUNT_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new AUTH_METHOD_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new CUSTOMER_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new CUSTOMER_NOT_VERIFIED enum value to the response property for the response status

    • warning

      added the new DOCUMENT_ALREADY_EXISTS enum value to the response property for the response status

    • warning

      added the new DOCUMENT_HOLDER_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new DUPLICATE_EXTERNAL_ACCOUNT enum value to the response property for the response status

    • warning

      added the new DUPLICATE_PAY_REQUEST enum value to the response property for the response status

    • warning

      added the new INSUFFICIENT_FUNDS enum value to the response property for the response status

    • warning

      added the new NOT_FOUND enum value to the response property for the response status

    • warning

      added the new PAYMENT_URL_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new PLATFORM_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new QUOTE_EXPIRED enum value to the response property for the response status

    • warning

      added the new QUOTE_RATE_UNAVAILABLE enum value to the response property for the response status

    • warning

      added the new REQUEST_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new SANCTION_BLOCKED enum value to the response property for the response status

    • warning

      added the new SESSION_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new SMS_OTP_CREDENTIAL_SET_CHANGED enum value to the response property for the response status

    • warning

      added the new SMS_OTP_PHONE_NUMBER_ALREADY_EXISTS enum value to the response property for the response status

    • warning

      added the new STABLECOIN_AMOUNT_NOT_REPRESENTABLE enum value to the response property for the response status

    • warning

      added the new STABLECOIN_BURN_SOURCE_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_GRID_OPERATIONS_NOT_ENABLED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new STABLECOIN_NOT_PROVISIONED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_OPERATION_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new STABLECOIN_OPERATION_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_PROVIDER_ERROR enum value to the response property for the response status

    • warning

      added the new STABLECOIN_PROVIDER_SOURCE_NOT_LINKED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_SYMBOL_ALREADY_EXISTS enum value to the response property for the response status

    • warning

      added the new STABLECOIN_TOKEN_IDENTIFIER_ALREADY_EXISTS enum value to the response property for the response status

    • warning

      added the new STABLECOIN_VERIFICATION_FAILED enum value to the response property for the response status

    • warning

      added the new VERIFICATION_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new WALLET_NOT_PROVISIONED enum value to the response property for the response status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • ccf658daca4bRevision changes
    • warning

      added the new BANK_ACCOUNT_VALIDATION_PENDING enum value to the response property for the response status