Before you issue
Create a card
status: "pending". last4 can be null until the card is issued; it arrives on a later card.updated. Full request and response: Create a card.
spend_limit.amountis in minor units:250000is $2,500.00. See Spend limits.nicknameis an optional display label, up to 64 characters.external_idis your own reconciliation key. It is not unique.spend_assetandspend_network_idname the asset and network the card spends: its wallet’s spend option, the same for every card on the wallet.last4is the only part of the card number the API ever returns. To show the full card, see Secure card data.
Wait for
card.updated with status: "active". Until then the card cannot be spent or revealed. Treat pending in your UI as “being issued”, not as an error.
Card status
Freeze, unfreeze, or close
PATCH /cards/{card_id} with the new status:
"active" to unfreeze and "closed" to close. Closing is permanent, so freeze when in doubt. A change applies to the next authorization: it does not release a hold or cancel a purchase that was already approved.
A closed card stays readable. GET /cards/{card_id} returns it with status: "closed". Lists leave it out unless you filter with status=closed. Every change to it, and a reveal, is refused with 403 card-closed: a PATCH that freezes, unfreezes, or renames it, and a new spend limit. The one exception: unfreezing a closed card whose cardholder is not active, and was not deleted, returns 403 cardholder-suspended first. Closing it again returns 200 with the card, which stays closed. Its transactions stay readable with GET /card_transactions?card_id=. A card closed by Dakota behaves the same way.
A card can be frozen by more than you. freeze_sources lists everything holding the card frozen. manual is a freeze applied through this API, and it is the only one you can lift. Treat any other value, including one you do not recognize, as a freeze you cannot lift. A card frozen because its cardholder is suspended shows frozen with an empty freeze_sources, and unfreezing it returns 403 cardholder-suspended.
Freezing is refused only for a closed card or an overdrawn one. Unfreezing can also be refused for these reasons:
Rename
nickname out, or sending null, keeps the current one. Nicknames do not have to be unique.
Spend limits
A card has at most one spend limit: aninterval and an amount in minor units. A card created without spend_limit has no per-card limit: it can spend up to the wallet’s available balance. Set a limit at creation, and replace it with PUT /cards/{card_id}/spend_limit:
intervalisper_transaction,daily,weekly,monthly,yearly, orlifetime.per_transactioncaps each purchase. A purchase exactly at the limit is allowed.daily,weekly,monthly, andyearlyare calendar windows that reset at midnight US Eastern Time: every day, every Monday, on the 1st of each month, and on January 1. They count authorized and settled spend in the current window, not a rolling period.lifetimecaps everything the card ever spends.- The new limit applies from the next purchase. Lowering it below what was already spent in the current window claws nothing back.
- A limit cannot be removed, only replaced.
- A limit is not a balance. A card with a $5,000 monthly limit on a wallet holding $200 can spend $200.
- If Dakota sets a program-wide cap for your account, the lower of the two wins.
- You can change the limit of a frozen card, but not of a closed one.
Read cards
GET /customers/{customer_id}/cards, filtered bycardholder_id,status, orexternal_id. Cursor-paginated.GET /cards/{card_id}. The response also embeds the cardholder and the wallet.
GET /cards/{card_id} returns a closed card, with status: "closed". The list leaves closed cards out unless you filter with status=closed. See Freeze, unfreeze, or close.
