diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 5c5219a31..12ee5f8ed 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -17934,7 +17934,7 @@ components: - authorizedAt - createdAt - updatedAt - description: 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. + description: 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 `CARD_TRANSACTION.*` webhooks on every status transition. properties: type: type: string diff --git a/mintlify/snippets/cards/reconciliation.mdx b/mintlify/snippets/cards/reconciliation.mdx index bb4e3b4c4..8b013f3d5 100644 --- a/mintlify/snippets/cards/reconciliation.mdx +++ b/mintlify/snippets/cards/reconciliation.mdx @@ -37,10 +37,9 @@ AUTHORIZED ──► PARTIALLY_SETTLED ──► SETTLED ──► REFUNDED | `REFUNDED` | A `RETURN` was received and the net settled amount has been refunded in full or part. | | `EXCEPTION` | The transaction settled to the network but the corresponding pull from the funding source failed. | -Every transition is delivered via the generic transaction webhook -stream carrying the post-change parent (a follow-up extends the -Transaction model with a card destination type — see -[Webhooks](/cards/platform-tools/webhooks)). +Every transition fires a `CARD_TRANSACTION.*` webhook carrying the +post-change parent — see [Webhooks](/cards/platform-tools/webhooks) +for the full list of event types. ## The over-auth path diff --git a/mintlify/snippets/cards/webhooks.mdx b/mintlify/snippets/cards/webhooks.mdx index c3318d863..89f7722ea 100644 --- a/mintlify/snippets/cards/webhooks.mdx +++ b/mintlify/snippets/cards/webhooks.mdx @@ -15,7 +15,7 @@ extends the Transaction model with a card destination type). | `CARD.STATE_CHANGE` | `PROCESSING → ACTIVE`, `→ CLOSED (ISSUER_REJECTED)`, and every subsequent `ACTIVE ⇄ FROZEN` and `→ CLOSED` transition. | | `CARD.FUNDING_SOURCE_CHANGE` | Whenever `PATCH /cards/{id}` updates the `fundingSources` array. | -All three carry the standard envelope: +All card webhooks carry the standard envelope: ```json { @@ -80,15 +80,22 @@ array. The `data` payload is the full `Card` resource with the post-change `fundingSources`, so a consumer that only cares about the current set of bindings can replace state wholesale. -## Card-transaction lifecycle +## CARD_TRANSACTION.* -Authorization, pull, clearing, refund, and `EXCEPTION` transitions are -not delivered through a dedicated card webhook. They flow through -the generic transaction webhook stream that already carries -outgoing-payment lifecycle events; a follow-up PR adds the card -destination type to that stream. See -[Reconciliation](/cards/transactions/reconciliation) for the -underlying event model. +Card-transaction lifecycle events fire on every state transition of a +`CardTransaction`. The `data` payload is the full `CardTransaction` +resource after the transition. + +| Type | Fires on | +|------|----------| +| `CARD_TRANSACTION.AUTHORIZED` | Authorization approved, hold placed on funding source. | +| `CARD_TRANSACTION.PARTIALLY_SETTLED` | At least one clearing landed, but more are expected (split shipments, multi-leg trips). | +| `CARD_TRANSACTION.SETTLED` | All clearings for the auth have posted. The transaction is closed. | +| `CARD_TRANSACTION.REFUNDED` | Merchant-initiated `RETURN` received; settled funds returned in full or part. | +| `CARD_TRANSACTION.EXCEPTION` | Transaction settled to the network but the pull from the funding source failed. | + +See [Reconciliation](/cards/transactions/reconciliation) for the +underlying event model and the over-auth and exception paths. ## Idempotency & retries diff --git a/mintlify/snippets/webhooks.mdx b/mintlify/snippets/webhooks.mdx index e1c2abfe1..91ccf6d41 100644 --- a/mintlify/snippets/webhooks.mdx +++ b/mintlify/snippets/webhooks.mdx @@ -203,3 +203,5 @@ The Grid API will retry webhooks with the following policy based on the webhook | `INVITATION.*` | Retry with exponential backoff up to 7 days with maximum interval of 30 mins | No retry on 409 (duplicate webhooks) | | `CUSTOMER.*` | Retry with exponential backoff up to 7 days with maximum interval of 30 mins | No retry on 409 (duplicate webhooks) | | `ACCOUNT.*` | Retry with exponential backoff up to 7 days with maximum interval of 30 mins | No retry on 409 (duplicate webhooks) | +| `CARD.*` | Retry with exponential backoff up to 7 days with maximum interval of 30 mins | No retry on 409 (duplicate webhooks) | +| `CARD_TRANSACTION.*` | Retry with exponential backoff up to 7 days with maximum interval of 30 mins | No retry on 409 (duplicate webhooks) | diff --git a/openapi.yaml b/openapi.yaml index 5c5219a31..12ee5f8ed 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -17934,7 +17934,7 @@ components: - authorizedAt - createdAt - updatedAt - description: 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. + description: 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 `CARD_TRANSACTION.*` webhooks on every status transition. properties: type: type: string diff --git a/openapi/components/schemas/cards/CardTransaction.yaml b/openapi/components/schemas/cards/CardTransaction.yaml index 87caed2fa..912e7cac1 100644 --- a/openapi/components/schemas/cards/CardTransaction.yaml +++ b/openapi/components/schemas/cards/CardTransaction.yaml @@ -17,9 +17,8 @@ description: >- 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. + aggregates. Delivered as the payload of `CARD_TRANSACTION.*` webhooks + on every status transition. properties: type: type: string