Terminology

Concepts and resources specific to the Cards API

The Cards API builds on top of the entities already used by the rest of Grid (Platform, Customer, Internal Account). The terms below are the ones that are new or have a card-specific meaning.

Cardholder

The Customer that a card is issued to. Cards are bound to a single cardholder, and the cardholder must have kycStatus: APPROVED before a card can be issued — otherwise POST /cards is rejected with CARDHOLDER_KYC_NOT_APPROVED.

Funding source

An InternalAccount bound to a card. Every card must be bound to at least one funding source, and Authorization Decisioning checks the source’s balance at auth time before approving a transaction. The fundingSources array on the Card resource is ordered by priority — the first entry is tried first. In v1 only the first source is read by Authorization Decisioning; additional sources are stored for future multi-source decisioning.

Authorization

The real-time request from the card network (“can this card spend $12.50 at Blue Bottle Coffee?”). Grid runs Authorization Decisioning against the funding source and either approves the auth (placing a hold) or declines it (INSUFFICIENT_FUNDS, CARD_PAUSED, etc.).

Pull

A debit against the bound internal account that funds an approved authorization. Most transactions have a single pull at auth time. A restaurant tip or any settlement larger than the original auth produces a second, post-hoc pull — this is the over-auth path.

Clearing (settlement)

The network’s confirmation that funds have moved for an authorization. A transaction can have multiple clearings (e.g. split shipments) and goes through AUTHORIZED → PARTIALLY_SETTLED → SETTLED as clearings land.

Refund

A merchant-initiated RETURN against a settled transaction. Refunds flow back to the funding source. A full refund moves the parent transaction to REFUNDED; a partial refund keeps it SETTLED with a non-zero refundedAmount.

Exception

A transaction that settled to the card network but whose corresponding pull from the funding source failed — for example, the cardholder’s balance no longer covers a post-hoc tip clearing. Exceptions are the high-urgency reconciliation alerts and are surfaced as status: "EXCEPTION" on the parent CardTransaction.

PAN embed URL

panEmbedUrl on the Card resource is the issuer’s iframe URL that renders the full PAN, CVV, and expiry directly to the cardholder. Render it in an iframe in your client; the full credentials never cross Grid’s servers.