Skip to main content
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 shape the API returns for it, with these differences:
  • An optional field with no value is left out, where the API sends it as null. returned_amount on card transactions is the exception: it is always present, and null when there is no refund. Some fields are left out by the API too, such as a card’s spend_limit when it has none. So read every optional field as “absent or null”.
  • A card event’s object does not embed the cardholder or the wallet.
  • A card transaction event’s object adds transacted_at: when the transaction happened, in Unix seconds.
None of the events on this page carries data.previous_attributes. To see what changed, compare the object with the copy you stored.

Events

A new card fires card.created with status: pending, then card.updated with status: active. Build against the second one. card.created and card.updated always carry freeze_sources: what is holding the card frozen as of that event’s version. It is an empty array when nothing is. card.created and card.updated also carry spend_asset and spend_network_id: the asset and network the card spends, which are its wallet’s spend option. They do not change. 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. Compare the event’s object with the one you stored while holding a lock on its id. Ignore it if it is older. If the two are equal, don’t apply the event’s copy, since one second can hold two changes. Instead, re-fetch the object while still holding that lock, and apply what you fetched. Because every re-fetch for an id happens under its lock, each one starts after the previous change was applied, so a fetched copy is never staler than what you stored. The lock covers one object, so it only delays other events for that same object. Give the re-fetch a short timeout. If it fails, release the lock and answer the webhook with an error so it is redelivered.

Enablement completed

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

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. Amounts such as auth_amount, cleared_amount and returned_amount are decimal strings in major units, with trailing zeros dropped: "39.5", and "39" for 39.00. Parse them as decimals; don’t match on the string. 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 usually a new card transaction on the same card, with status: returned. The original purchase stays cleared, and the refund is not linked to it. Sometimes the refund lands on the purchase’s own transaction instead. That transaction keeps its cleared_amount. While the refund covers only part of what cleared, it also keeps its purchase status (cleared, partially_cleared or force_posted); once the refunds cover everything that cleared, and nothing authorized is still waiting to clear, its status becomes returned, with cleared_amount still non-zero. So don’t decide what is a refund from status. A transaction carries a refund whenever it has a refund_state that is not null, whatever its status. On a transaction with no refund, the API returns refund_state: null, while webhook payloads leave refund_state out entirely, so check for a value rather than for an explicit null. returned_amount is always present on both, null when there is no refund. returned_amount is how much was refunded: the total of every refund on that transaction, less any refund the merchant later reversed. It changes on card_transaction.updated as further refunds or reversals arrive, so it can go up or down. It is "0" once every refund on it was reversed. A refund reversed before it was paid ends refund_state: reversed. One reversed after it was paid keeps refund_state: paid with the lower returned_amount; see below for settling it. A standalone refund reversed in full also moves from status: returned to auth_reversed. On a refund whose amount has not arrived yet, such as one made before this field existed, returned_amount is null while refund_state is set, until a card_transaction.updated fills it in. A standalone refund’s cleared_amount is "0" and its auth_amount may be null, so always read the refunded amount from returned_amount. refund_state says whether the money has reached the wallet: pending, then paid, or it ends reversed or failed. Credit the cardholder only when refund_state is paid. status: returned alone means only that the network sent the money back. When a transaction carries more than one refund, refund_state sums them up in this order: pending while any refund on it is still owed, else failed if any payout failed, else paid, else reversed. So a transaction whose first refund was paid reads pending again when a second refund arrives. While it reads pending or failed, returned_amount includes money that has not reached the wallet yet. returned_amount is a running total for the whole transaction, and refund_state can stay paid across later events, including redeliveries. So never credit returned_amount itself on each event. Instead, keep a settled total for each transaction id: what you have credited, less what you have debited back or flagged. Settle against it by refund_state:
  • returned_amount is null: the amount has not arrived. Settle nothing, whatever refund_state says.
  • paid: every refund on the transaction is either paid or reversed, so returned_amount is exactly what the cardholder should keep. Take the difference between returned_amount and your settled total:
    • Positive: credit it.
    • Negative: the merchant reversed a refund after it was paid. Debit it back, or flag it for review and recover it separately. Never ignore it.
    • Zero: a repeated or redelivered event; do nothing.
    Then set the settled total to returned_amount, whether you debited or flagged. Redeliveries then find nothing to settle, and a later refund is credited in full rather than netted against a reversal you are recovering.
  • pending: settle nothing yet. Part of returned_amount has not been paid, so the difference cannot be split. A reversal of a refund you already credited is not lost: once the pending refund is paid, the transaction reads paid and the difference includes the reversal.
  • failed: settle nothing, and flag the transaction for review. A payout failed, and these fields cannot tell its amount apart from refunds already paid or reversed. Contact Dakota support with the transaction id.
  • reversed: every refund was reversed before it was paid, so there is nothing to settle. If your settled total is not zero, flag it.
Delivery is at least once, and two events for the same transaction can arrive together or out of order. So do the staleness check, the read, the credit and the store as one atomic step per transaction id, under a lock on that id. A conditional update alone is not enough, because the re-fetch on an equal updated_at has to run under the lock. Otherwise two events can both see the old total and credit the same difference twice, or an older event can be settled after a newer one.
Refund payouts to the wallet are not live yet. Until they are, refund_state is pending, or reversed if the merchant reverses the refund. It does not reach paid or failed.

Declines

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

A handler

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