--- title: "Card transaction" method: POST path: "card-transaction" tags: ["Webhooks"] --- # Card transaction `POST card-transaction` (webhook) Webhook that is called on every state transition 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 settled funds are returned (`CARD_TRANSACTION.REFUNDED`), and when a pull or confirmation fails (`CARD_TRANSACTION.EXCEPTION`). The payload carries the full `CardTransaction` resource. 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. ## Payload - CardTransactionWebhook - `id` string, required — Unique identifier for this webhook delivery (can be used for idempotency) - `type` 'CARD_TRANSACTION.AUTHORIZED' | 'CARD_TRANSACTION.PARTIALLY_SETTLED' | 'CARD_TRANSACTION.SETTLED' | 'CARD_TRANSACTION.REFUNDED' | 'CARD_TRANSACTION.EXCEPTION', required — Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot identifies the resource, the part after identifies the event. This lets consumers route purely on type without inspecting data.status. - `timestamp` string, date-time, required — ISO 8601 timestamp of when the webhook was sent - `data` CardTransaction, required — Parent transaction row for a card authorization and all of the pulls / settlements / refunds that reconcile against it. Child events are rolled up into the `pullSummary`, `refundSummary`, and `settlementSummary` aggregates. Delivered as the payload of the generic transaction webhook stream (extends the Transaction model with a card destination type) on every transition. - `type` 'CARD', required — Discriminator identifying this transaction as a card transaction in the `Transaction` list. - `id` string, required — System-generated unique card transaction identifier - `cardId` string — The id of the `Card` this transaction was made on. - `customerId` string, required — System ID of the customer (cardholder) this transaction belongs to. - `platformCustomerId` string, required — Platform-specific ID of the customer (cardholder) this transaction belongs to. - `issuerTransactionToken` string — Opaque identifier for the transaction on the underlying issuer. Used to cross-reference Grid records against issuer dashboards and webhooks. - `status` 'AUTHORIZED' | 'PARTIALLY_SETTLED' | 'SETTLED' | 'REFUNDED' | 'EXCEPTION', required — Lifecycle status of a card transaction. | Status | Description | |--------|-------------| | `AUTHORIZED` | The auth has been approved and a hold placed on the funding source; no clearing has arrived yet. | | `PARTIALLY_SETTLED` | At least one clearing has arrived and posted, but more clearings are still expected (split shipments, tips, multi-leg trips). | | `SETTLED` | All clearings for the auth have posted and the transaction is closed against the funding source. | | `REFUNDED` | A `RETURN` was received from the merchant; the net settled amount has been refunded in part or whole. | | `EXCEPTION` | The transaction settled to the card network but the corresponding pull from the funding source failed (e.g. balance no longer covers the post-hoc clearing). Surfaces high-urgency alerts and is the dashboard query for stuck reconciliations. | - `direction` 'CREDIT' | 'DEBIT', required — Whether the transaction credits (funds in) or debits (funds out) the customer's account. Independent of `type`: an incoming transaction is normally a `CREDIT`, but an inbound ACH pull, for example, is an `INCOMING` transaction with a `DEBIT` direction. - `merchant` CardMerchant, required - `descriptor` string, required — Merchant descriptor string captured from the card network at authorization time. - `mcc` string — Merchant Category Code (ISO 18245) — four-digit numeric string. - `country` string — Two-letter ISO 3166-1 alpha-2 country code of the merchant. - `authorizedAmount` CurrencyAmount, required - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) - `currency` Currency, required - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - `name` string — Full name of the currency - `symbol` string — Symbol of the currency - `decimals` integer — Number of decimal places for the currency - `settledAmount` CurrencyAmount - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) - `currency` Currency, required - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - `name` string — Full name of the currency - `symbol` string — Symbol of the currency - `decimals` integer — Number of decimal places for the currency - `refundedAmount` CurrencyAmount - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) - `currency` Currency, required - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - `name` string — Full name of the currency - `symbol` string — Symbol of the currency - `decimals` integer — Number of decimal places for the currency - `accountId` string, required — Internal account id that funded this transaction (the funding source selected by Authorization Decisioning at auth time). - `pullSummary` CardPullSummary - `count` integer, required — Total number of pulls (debits) executed against the funding source for this transaction. `> 1` indicates one or more post-hoc pulls — e.g. restaurant tip / over-auth clearings. - `totalAmount` integer, required — Sum of all pull amounts in the smallest unit of the funding source's currency. - `pendingCount` integer — Number of pulls still in the `PENDING` state. Drops to zero when every pull has reached a terminal state. Non-zero values that persist beyond the expected settlement window are an early signal for the `EXCEPTION` path. - `refundSummary` CardRefundSummary - `count` integer, required — Number of refund (return) events received for this transaction. - `totalAmount` integer, required — Sum of all refund amounts in the smallest unit of the funding source's currency. - `settlementSummary` CardSettlementSummary - `count` integer, required — Number of settlement (clearing) events received for this transaction. - `totalAmount` integer, required — Sum of all settled amounts in the smallest unit of the funding source's currency. - `authorizedAt` string, date-time, required — When the auth was approved. - `lastEventAt` string, date-time — Timestamp of the most recent reconcile event (pull / clearing / refund) against this transaction. - `createdAt` string, date-time, required — Creation timestamp (same as `authorizedAt` for card transactions). - `updatedAt` string, date-time, required — Last update timestamp. ## Acknowledgement `200` Webhook received successfully ## Other responses - `400` — Bad request - `401` — Unauthorized - Signature validation failed - `409` — Conflict - Webhook has already been processed (duplicate id) --- [API](https://skmtc.net/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.net/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stainless-api/grid-api/revisions/151f2d9bad9c/schema)