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.
A card has no balance of its own. A purchase is authorized against the wallet’s available balance and held until the merchant clears it. The cleared amount is then settled out of the wallet under its card enablement.

​
A purchase, end to end

  • Authorization happens at the terminal. Nothing moves yet; the amount is held.
  • Clearing happens when the merchant captures the sale, sometimes for a different amount. That is when funds leave the wallet. Dakota batches recoveries per wallet rather than moving funds once per purchase.

​
Holds and available balance

Cards spend one token on one network: Dakota’s RD token on Base, or USDC where RD is not yet supported. Only that token on that network counts toward the card balance. A deposit of another token, or of the same token on another network, does not fund cards, and purchases decline with insufficient_funds. In sandbox, cards spend testnet RD on Base Sepolia. A hold reduces what every card on the wallet, and every ordinary send from it, can spend. That is what makes several cards on one wallet safe. GET /wallets/{wallet_id}/balances returns the four figures in a card object:
  • The figures never overstate what the wallet can spend: total is rounded down, held and outstanding are rounded up.
  • card is present while the wallet’s enablement is active, detach_requested, or detached, because a detached wallet can still owe an outstanding amount. It is absent, never null, when there is no enablement or it is still attaching. It is also absent when the live read fails or is slow; treat that as “try again later”, not as an error. The other balances fields are the same either way.
A hold can be larger than the purchase. Every authorization holds a little more than its amount to cover network adjustments, and merchants such as restaurants, fuel pumps, and hotels hold more because they often clear for more than they authorize. The excess is released when the transaction clears, so a purchase for the entire available balance can be declined. A hold the merchant never clears expires under network rules, and the funds become available again.

​
Outcomes

  • Declined purchases hold nothing and move nothing. They are recorded as a card transaction with status: declined and a decline_reason, and never change after that.
  • Refunds are a new card transaction on the same card, with status: returned. The original purchase stays cleared, and the refund is not linked to it. refund_state reports whether the money has reached the wallet: see Refunds.
  • Force posts are clearings with no prior authorization. Networks allow them and they cannot be declined.

​
When a wallet comes up short

A hold reserves the money before a purchase is approved, so almost every transaction is covered. Two cases can still leave a gap: a force post, and a clearing larger than its hold, such as a cross-border fee. Dakota has already paid the network by then, so the gap becomes the wallet’s outstanding amount. Dakota recovers it as the wallet is funded again. The wallet balance is never shown as negative.

​
Reading transactions

Every stage arrives as a webhook: see Card transactions. To backfill or reconcile, use GET /card_transactions, filtered by customer_id, card_id, or cardholder_id, and GET /card_transactions/{card_transaction_id}.