Update a card

Update a card's state and / or its bound fundingSources. At least one of the two fields must be supplied.

• state transitions are limited to ACTIVE ⇄ FROZEN and ACTIVE | FROZEN → CLOSED. CLOSED is terminal and irreversible. Any other transition returns 409 INVALID_STATE_TRANSITION.
• fundingSources, when supplied, fully replaces the card's bound funding sources. Array order determines the priority Authorization Decisioning tries them in. Each id must belong to the cardholder and be denominated in the card's currency; the list must contain at least one source. fundingSources cannot be supplied alongside state: CLOSED.

This endpoint is authenticated by the platform credential alone and returns 200 directly. It deliberately does not use Grid's 202 → signed-retry pattern: that pattern signs with the session key of a credential on the owning internal account, so it models actions taken by the end user on their own credentials or funds. Freezing or closing a card is routinely an action taken about a user and without them present - fraud response, offboarding, an ops-driven freeze - and requiring the cardholder's signature would make exactly those cases impossible. Operations that expose sensitive card data (POST /cards/{id}/reveal, 3DS password retrieval) are SCA-railed instead, because there the cardholder is the party being served.

Effects:

• state: FROZEN: Authorization Decisioning declines new auths with CARD_PAUSED. Existing pulls and in-flight reconciliation continue — freezing does not pause the lifecycle of authorizations that already passed.
• state: ACTIVE: normal authorization behavior resumes.
• state: CLOSED: terminal close. The card transitions to state: "CLOSED" with stateReason: "CLOSED_BY_PLATFORM" and stays in the system for audit and reconciliation. All pending auths reconcile to a terminal state via the existing reconcile primitive. Inbound clearings received after close follow the standard force-post / late-presentment path — Lightspark absorbs the loss if a post-hoc pull on the now-unbound source fails. Funding-source bindings are detached. Refunds already in flight still complete because Lightspark holds the card-reserve keys.
• fundingSources change: emits card.funding_source_change reflecting the new ordered binding.

The card.state_change webhook fires on every successful state transition; the card.funding_source_change webhook fires whenever fundingSources is updated.