Cards Webhooks

Cards is available in sandbox only while we finish development. Dakota enables Cards per account. The Cards endpoints are in the API reference, marked Sandbox only. Endpoints, fields, and flows can still change before release.

Card events arrive on your existing webhook stream, in the standard envelope, with the same signing and retries. See Webhook Integration for delivery. Delivery is at least once, so dedupe on the event id. If your webhook target filters by type, add the card events first. A target with global: false receives only the types in its event_types list. A card event type missing from that list is never delivered and never retried. Targets with global: true receive card events automatically. data.object is the resource that changed, in the same shape the API returns for it. On updates, data.previous_attributes holds the prior values of the fields that changed.

Events

Event	Fires when	`data.object`
`customer.capability_status.updated`	A customer’s capability changes status. Filter on `capability: "cards"`.	The capability
`wallet.card_enablement.completed`	A wallet’s enablement becomes `active`. Cards can now be issued against it.	The acceptance record: see below
`cardholder.created`	A cardholder is created.	Cardholder
`cardholder.updated`	Any change to a cardholder, including its status moving to `active` or `closed`.	Cardholder
`cardholder.information_requested`	A reviewer asks you for information. Not live yet.	The open requests
`card.created`	A card is issued, still `pending`.	Card
`card.updated`	A card changes: activation, freeze, unfreeze, close, or a new spend limit.	Card
`card_transaction.created`	A card transaction is first recorded: an authorization, a decline, a refund, or a force post.	Card transaction
`card_transaction.updated`	Anything later happens to that transaction.	Card transaction

A new card fires card.created with status: pending, then card.updated with status: active. Build against the second one. Events can arrive out of order (see Event ordering), so card.created can land after card.updated.

Cards carry version, which goes up by one on every card event. Keep the highest version you have applied for each card, and drop any event or response whose version is not greater.
Cardholders and card transactions carry updated_at, in seconds. Ignore an event whose object is older than the one you stored, and re-fetch the object when the two are equal.

Enablement completed

wallet.card_enablement.completed records what the customer signed. Keep it as their acceptance record.

Field	Meaning
`wallet_id`, `customer_id`, `client_id`	Who and what the enablement covers
`intent_kind`	Always `enable_card_settlement`
`intent_hash`	Hash of the exact intent the customer signed
`signatures`	Every signature submitted with the intent. `signature` repeats the first one.
`signer_public_key`	The key that signed. Empty when the signer could not be identified.
`settlement_destination`	The one address Dakota can recover settled card spend to
`completed_at`	When the enablement became `active`, in Unix seconds

Card transactions

A card transaction is one purchase, refund, or other network event on a card. Its id stays the same for its whole life. Its first state arrives on card_transaction.created and later ones on card_transaction.updated, but a status can arrive on either event: a transaction can start pending and become authorized on an update, and a decline can arrive on an update too. Upsert by data.object.id and switch on status, not on the event type. There are no separate hold, release, or settlement events.

`status`	Meaning
`pending`	Recorded before its first authorization was applied.
`authorized`	Approved. The amount is held; nothing has settled.
`declined`	Refused. Nothing was held and no money moved. `decline_reason` says why. Final.
`partially_cleared`	Part of the amount has settled; more is expected.
`cleared`	Settled.
`auth_reversed`	The merchant cancelled before capturing. The hold was released.
`expired`	Never captured. The hold was released.
`force_posted`	Settled with no prior authorization, so nothing was held first.
`returned`	A merchant refund. See Refunds.
`disputed`	Reserved. Not sent yet.

Amounts such as auth_amount and cleared_amount are decimal strings in major units ("39.00"). The card’s spend_limit.amount is different: an integer in minor units. outstanding_amount is the part of cleared_amount that no authorization covered, less any refunds. It is non-zero after a force post, or when a merchant clears more than it authorized.

Refunds

A merchant refund is a new card transaction on the same card, with status: returned. The original purchase stays cleared, and the refund is not linked to it. status: returned means the network sent the money back. refund_state says whether it has reached the wallet: pending, then paid, or it ends reversed or failed. Credit the cardholder only when refund_state is paid. It is null on every transaction that is not a refund.

Refund payouts to the wallet are not live yet. Until they are, refund_state stays pending.

Declines

`decline_reason`	Meaning
`insufficient_funds`	The wallet’s available balance was too low.
`card_inactive`	The card was not active, for example frozen.
`spend_limit_exceeded`	The purchase would exceed the card’s spend limit.
`merchant_not_allowed`	A merchant or category restriction refused it.
`card_details_incorrect`	The card number, expiry, or CVV did not match.
`suspected_fraud`	Refused as suspected fraud.
`authorization_timeout`	No decision was reached in time.
`other`	Anything else. Treat any value you do not recognize as `other`.

decline_code is the raw network code. Use it for support only; do not build logic on it.

A handler

on any card.* event:
  skip it unless data.object.version is greater than the version you stored
  "active" → the card can be spent and revealed
  "frozen" → show it as frozen; the freeze may not have come from you (check freeze_sources)
  "closed" → stop offering the card

on card_transaction.created or card_transaction.updated:
  skip it if data.object.updated_at is older than the transaction you stored
  upsert the transaction by data.object.id, then switch on status:
    "pending", "authorized"       → show a pending charge for auth_amount
    "declined"                    → show a declined attempt, worded from decline_reason
    "partially_cleared", "cleared",
    "force_posted"                → show the charge at cleared_amount
    "auth_reversed", "expired"    → remove the pending charge; no money moved
    "returned"                    → show a pending refund; credit it when refund_state is "paid"

Card events never contain the full card number, expiry, or CVV. last4 is the most they carry.

Playground

Documentation

Import Share Tokens

Agentic Payments

Cards

Authentication

Developer Tools

Cards Webhooks

Events

Enablement completed

Card transactions

Refunds

Declines

A handler

​Events

​Enablement completed

​Card transactions

​Refunds

​Declines

​A handler

Events

Enablement completed

Card transactions

Refunds

Declines

A handler