Skip to content

docs: update card webhook documentation for CARD_TRANSACTION events #693

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
claude wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: update card webhook documentation for CARD_TRANSACTION events #693

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion mintlify/openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 3 additions & 4 deletions mintlify/snippets/cards/reconciliation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
25 changes: 16 additions & 9 deletions mintlify/snippets/cards/webhooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down Expand Up @@ -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

Expand Down
2 changes: 2 additions & 0 deletions mintlify/snippets/webhooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
2 changes: 1 addition & 1 deletion openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 2 additions & 3 deletions openapi/components/schemas/cards/CardTransaction.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading