Quickstart

This quickstart walks you from an empty Sandbox to a card transaction you can see in your dashboard. We’ll:

Confirm the cardholder is KYC-approved.
Fund their internal account.
Issue a virtual card against that account.
Simulate an inbound authorization, then a clearing.
List the resulting CardTransaction.

Prerequisites

Sandbox API credentials.
A Customer with kycStatus: APPROVED and at least one InternalAccount. If you don’t have one yet, follow the Payouts quickstart up to “Get the Customer’s Internal Account”.

export GRID_BASE_URL="https://api.lightspark.com/grid/2025-10-13"
export GRID_CLIENT_ID="YOUR_SANDBOX_CLIENT_ID"
export GRID_CLIENT_SECRET="YOUR_SANDBOX_CLIENT_SECRET"

Fund the cardholder’s internal account

Cards decline at auth time if the bound funding source can’t cover the transaction. Top up the cardholder’s internal account first.

curl -X POST "$GRID_BASE_URL/sandbox/internal-accounts/InternalAccount:019542f5-b3e7-1d02-0000-000000000002/fund" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50000 }'

Issue the card

curl -X POST "$GRID_BASE_URL/cards" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "form": "VIRTUAL",
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
  }'

The card comes back in state: "PROCESSING" while the issuer provisions it. platformCardId is generated by the server, and any value supplied in the request is ignored. When activation completes, a CARD.STATE_CHANGE webhook fires with state: "ACTIVE":

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000020",
  "type": "CARD.STATE_CHANGE",
  "timestamp": "2026-05-08T14:11:00Z",
  "data": {
    "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "state": "ACTIVE",
    "brand": "VISA",
    "form": "VIRTUAL",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2029,
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "currency": "USD",
    "processorRef": "card_b81c2a4f",
    "issuerRef": "lead_card_7a1b9c3d",
    "createdAt": "2026-05-08T14:10:00Z",
    "updatedAt": "2026-05-08T14:11:00Z"
  }
}

To display the full PAN, CVV, and expiry to the cardholder, request a reveal with POST /cards/{id}/reveal and render the returned panEmbedUrl in an iframe. The URL is short-lived, so request it right before rendering. The full card credentials never cross your servers.

Simulate an authorization

Sandbox exposes simulate endpoints that drive the same internal paths the card issuer would call in production. The decisioning outcome is controlled by the last three characters of merchant.descriptor — any non-magic suffix is approved.

curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-000000000010/simulate/authorization" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1250,
    "currency": { "code": "USD" },
    "merchant": {
      "descriptor": "BLUE BOTTLE COFFEE SF",
      "mcc": "5814",
      "country": "US"
    }
  }'

The response is the resulting CardTransaction in status: "AUTHORIZED" with a single pull on the funding source.

Simulate the clearing

The merchant adds a tip and clears for more than the original auth (

15.00 on a

12.50 hold). Grid handles the over-auth by issuing a post-hoc pull for the difference.

curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-000000000010/simulate/clearing" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "cardTransactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000100",
    "amount": 1500
  }'

A transaction webhook fires with the updated parent: the transaction moves to SETTLED and settledAmount is 1500. The webhook payload carries the full CardTransaction with clearings rolled up into settledAmount; a merchant refund posts as its own dated CREDIT row linked via originalTransactionId — see Reconciliation for the full event model.

You’ve issued a card, watched it activate, and driven an over-auth transaction through pull and clearing.

Overview

Onboarding

Card management

Transactions

Card design

Platform tools

Prerequisites

Fund the cardholder’s internal account

Issue the card

Simulate an authorization

Simulate the clearing

​Prerequisites

​Fund the cardholder’s internal account

​Issue the card

​Simulate an authorization

​Simulate the clearing

Prerequisites

Fund the cardholder’s internal account

Issue the card

Simulate an authorization

Simulate the clearing