Card transaction

Webhook that is called on every lifecycle update of a card CardTransaction. Fires when an authorization is approved (CARD_TRANSACTION.AUTHORIZED), as clearings settle against it (CARD_TRANSACTION.PARTIALLY_SETTLED, CARD_TRANSACTION.SETTLED), when the authorization is declined (CARD_TRANSACTION.DECLINED), when an authorization is fully reversed or expires (CARD_TRANSACTION.VOIDED), and when a transaction settles to the card network but the funding-source pull fails (CARD_TRANSACTION.EXCEPTION). The payload carries the full CardTransaction resource.

A merchant return is its own CardTransaction row (direction: CREDIT) linked to the purchase via originalTransactionId, and fires its own CARD_TRANSACTION.* deliveries on that row — the purchase row is not re-fired for the return.

This endpoint should be implemented by clients of the Grid API.

Authentication

The webhook includes a signature in the X-Grid-Signature header that allows you to verify that the webhook was sent by Grid. To verify the signature:

1. Get the Grid public key provided to you during integration
2. Decode the base64 signature from the header
3. Create a SHA-256 hash of the request body
4. Verify the signature using the public key and the hash

If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

WEBHOOK card-transaction

JSON

authorized

{
  "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"
  }
}

400

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

Authorizations

X-Grid-Signature · string · header · required

Secp256r1 (P-256) asymmetric signature of the webhook payload, which can be used to verify that the webhook was sent by Grid. To verify the signature:

1. Get the Grid public key provided to you during integration
2. Decode the base64 signature from the header
3. Create a SHA-256 hash of the request body
4. Verify the signature using the public key and the hash

If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

Body

application/json

id · string · required

Unique identifier for this webhook delivery (can be used for idempotency)

Example:

"Webhook:019542f5-b3e7-1d02-0000-000000000007"

type · enum<string> · required

Status-specific event type in OBJECT.EVENT dot-notation (e.g., OUTGOING_PAYMENT.COMPLETED)

Available options: CARD_TRANSACTION.AUTHORIZED, CARD_TRANSACTION.PARTIALLY_SETTLED, CARD_TRANSACTION.SETTLED, CARD_TRANSACTION.DECLINED, CARD_TRANSACTION.VOIDED, CARD_TRANSACTION.EXCEPTION

timestamp · string<date-time> · required

ISO 8601 timestamp of when the webhook was sent

Example:

"2025-08-15T14:32:00Z"

data · Card Transaction · object · required

One row per cardholder-visible card transaction. A purchase row rolls its clearings up into settledAmount; a merchant return is its own dated CREDIT row linked back to the purchase via originalTransactionId rather than a rollup on the parent, so statements can list purchases and refunds as separate dated lines. Delivered whole as the data payload of every CARD_TRANSACTION.* webhook, and returned as the CARD variant of Transaction from GET /transactions.

Show child attributes

Response

200

Webhook received successfully