Skip to main content
This page gives you a 10,000-ft view of an end-to-end Cards implementation. The detailed guides that follow cover concrete request shapes, edge cases, and step-by-step instructions.
Cards sit on top of the same customer and internal-account primitives you already use for payouts. If you’ve already onboarded customers and funded internal accounts in Grid, the work to add cards is small.

​
Platform configuration

You need an existing Grid platform configuration before you can issue cards. Cards do not require new webhook endpoints or new API credentials — they reuse what’s already configured for the rest of Grid. You’ll only need to:
  • Subscribe to the card webhook types: CARD.STATE_CHANGE for card state, and CARD_TRANSACTION.AUTHORIZED, CARD_TRANSACTION.PARTIALLY_SETTLED, CARD_TRANSACTION.SETTLED, CARD_TRANSACTION.DECLINED, and CARD_TRANSACTION.EXCEPTION for the transaction lifecycle.
  • Confirm with your Lightspark contact that cards are enabled for your platform — issuance requires an issuer-side onboarding.
  • If your program includes physical cards, start the artwork early: design review, Visa approval, and manufacturing run for weeks. See Card design guidelines.

​
Cardholder readiness

A card can only be issued to a Customer with kycStatus: APPROVED. This is the same gate you use for Grid’s other features. If the cardholder hasn’t completed KYC, POST /cards returns 400 CARDHOLDER_KYC_NOT_APPROVED — see Cardholder setup for how to drive KYC to completion before issuing.

​
Funding sources

Every card is bound to one InternalAccount as its funding source at issue time. Authorization Decisioning checks the source’s balance before approving each auth, so:
  • Top up the funding source before you expect transactions.
  • Use existing funding instructions (ACH, SEPA, wires, stablecoin) the same way you would for any other internal account.
  • See Funding sources for rules around binding and replacing the source.

​
Issuing and lifecycle

Issuance is a single POST /cards call. New cards start in PROCESSING while the issuer provisions them and transition to ACTIVE automatically — you observe both transitions via the CARD.STATE_CHANGE webhook. Day-to-day operational changes are:
  • PATCH /cards/{id} to freeze, unfreeze, or close permanently (state: "CLOSED").
Both freeze and close use Grid’s 202 → signed-retry pattern (the same pattern as Embedded Wallet credential revocation). See Freezing and closing cards.

​
Transactions and reconciliation

Each authorization on a card produces a CardTransaction row, with clearings reconciled against it and rolled up into settledAmount. The lifecycle status moves AUTHORIZED → PARTIALLY_SETTLED → SETTLED, with DECLINED for auths refused before any money moved and EXCEPTION as the failure path for stuck post-hoc pulls. A merchant return is its own dated CREDIT CardTransaction row linked to the purchase via originalTransactionId; the purchase keeps its SETTLED status. The full event model is covered in Reconciliation.

​
Testing in Sandbox

Sandbox cannot receive real authorizations from the card network, so it exposes three simulate endpoints that drive the same internal paths the issuer would call in production:
  • POST /sandbox/cards/{id}/simulate/authorization
  • POST /sandbox/cards/{id}/simulate/clearing
  • POST /sandbox/cards/{id}/simulate/return
Outcomes are deterministic — driven by magic-value suffixes on the relevant id. See Sandbox testing.

​
Enabling Production

When you’re ready to go live:
  • Complete card-issuer onboarding through your Lightspark contact.
  • Confirm webhook security, monitoring, and alerting cover the CARD.* and CARD_TRANSACTION.* event types.
  • Build the EXCEPTION dashboard view from CARD_TRANSACTION.EXCEPTION webhooks and wire it into on-call alerting.
Contact your Lightspark representative to enable Production card issuance and finalize issuer activations.