Webhooks

Card webhook events and how to consume them

Cards add eight webhook event types on top of Grid’s existing webhook infrastructure. Signature verification (X-Grid-Signature) and retry behavior are identical to the rest of Grid — see Authentication and Webhooks for the underlying mechanics.

Two cover the card itself; the others cover a card transaction’s lifecycle.

Event types

Type	Fires on
CARD.STATUS_CHANGE	PROCESSING → ACTIVE, → CLOSED (ISSUER_REJECTED), and every subsequent ACTIVE ⇄ FROZEN and → CLOSED transition.
CARD.PIN_STATUS_CHANGE	Grid records a new PIN status, such as NOT_SET → OK, OK → BLOCKED, or BLOCKED → OK.
CARD_TRANSACTION.AUTHORIZED	An authorization is approved and a hold is placed on the funding source.
CARD_TRANSACTION.PARTIALLY_SETTLED	A clearing posted, but more are still expected.
CARD_TRANSACTION.SETTLED	All clearings have posted. Also fires for a merchant return, which posts as its own CREDIT row linked via originalTransactionId.
CARD_TRANSACTION.DECLINED	The authorization was declined before any money moved. The payload carries cardDeclinedReason.
CARD_TRANSACTION.VOIDED	An approved authorization was fully reversed or expired before any clearing posted.
CARD_TRANSACTION.EXCEPTION	The transaction settled to the network but the pull from the funding source failed.

All of them carry the standard envelope:

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000020",
  "type": "CARD.STATUS_CHANGE",
  "timestamp": "2026-05-08T14:11:00Z",
  "data": { /* the affected Card or CardTransaction resource */ }
}

The id identifies an event and stays the same across delivery retries. Use it for idempotency.

CARD.STATUS_CHANGE

The data payload is the post-change Card resource. Example — activation after issuance:

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000020",
  "type": "CARD.STATUS_CHANGE",
  "timestamp": "2026-05-08T14:11:00Z",
  "data": {
    "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "status": "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"
  }
}

Common branches to handle in your consumer:

• status: "ACTIVE" after PROCESSING — the card is live. To reveal the full card details, request a reveal with POST /cards/{id}/reveal right before rendering its short-lived panEmbedUrl in an iframe — webhook payloads never carry a reveal URL.
• status: "CLOSED", statusReason: "ISSUER_REJECTED" — the issuer rejected provisioning; offer to issue a new card.
• status: "FROZEN" / status: "ACTIVE" — reflect the freeze toggle in your UI.
• status: "CLOSED", statusReason: "CLOSED_BY_PLATFORM" — close confirmed; stop showing the card.

CARD.PIN_STATUS_CHANGE

The data payload is the updated Card resource, including pinStatus. Use it to offer PIN setup when the status is NOT_SET, reflect a configured PIN when it is OK, or offer recovery when it is BLOCKED.

This event fires when Grid’s saved PIN status changes, whether the change is observed through a PIN API request or an asynchronous update after an iframe submission or an incorrect PIN attempt. Creating a card does not fire it. Replacing an existing PIN while its status stays OK also does not fire it; use the submission result to confirm that change.

The payload never includes a PIN, encrypted PIN block, or session credential. Delivery can lag behind a change or arrive out of order. Compare data.updatedAt before replacing a newer card snapshot. Read pinStatus from GET /cards/{id} to retrieve the card’s saved status. See Card PINs for the setup and recovery flows.

Card-transaction lifecycle

The data payload is the whole post-change CardTransaction resource, the same shape GET /transactions returns for a CARD row, so you can upsert it by data.id without a follow-up read. Example — authorization approved:

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000040",
  "type": "CARD_TRANSACTION.AUTHORIZED",
  "timestamp": "2026-05-09T10:00:00Z",
  "data": {
    "type": "CARD",
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000100",
    "cardId": "Card:019542f5-b3e7-1d02-0000-000000000010",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCustomerId": "18d3e5f7b4a9c2",
    "issuerTransactionToken": "lithic_txn_b81c2a4f",
    "status": "AUTHORIZED",
    "direction": "DEBIT",
    "description": "BLUE BOTTLE COFFEE SF",
    "merchant": {
      "descriptor": "BLUE BOTTLE COFFEE SF",
      "mcc": "5814",
      "country": "US"
    },
    "authorizedAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "authorizedAt": "2026-05-09T10:00:00Z",
    "createdAt": "2026-05-09T10:00:00Z",
    "updatedAt": "2026-05-09T10:00:00Z"
  }
}

Later deliveries for this approved authorization carry the updated resource: settledAmount appears once a clearing posts, and status moves to PARTIALLY_SETTLED, SETTLED, VOIDED, or EXCEPTION. A declined authorization instead reports DECLINED as its terminal decision. A merchant return has no event type of its own — it arrives as a CARD_TRANSACTION.SETTLED delivery for a new data.id with direction: "CREDIT" and originalTransactionId pointing at the purchase, so key your handling on data.id rather than on the event type. See Reconciliation for the underlying event model.

Idempotency & retries

Webhook deliveries are at-least-once. Track processed id values and return 200 on duplicates, or return 409 and let Grid stop retrying. Both shapes are accepted by Grid’s webhook infrastructure.