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. The cleared amount stays held on the wallet until settlement.
- Settlement is when funds leave the wallet. Dakota batches recoveries per wallet in a settlement sweep, rather than moving funds once per purchase. Cleared spend stays in
helduntil the sweep that collects it is confirmed on-chain. Thenheldandtotalboth drop by the swept amount, andavailabledoes not change.
Holds and available balance
Cards spend one token on one network, the wallet’s spend option: RD on Base by default, or another option you choose when you enable the wallet. 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 withinsufficient_funds. In sandbox, the default is 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, with the spend option they are measured in:
spend_assetandspend_network_idname the asset and network the figures are for. They are the wallet’s spend option and never change.- The figures never overstate what the wallet can spend:
totalis rounded down,heldandoutstandingare rounded up. cardis present while the wallet’s enablement isactive,detach_requested, ordetached, because a detached wallet can still owe an outstanding amount. It is absent, nevernull, when there is no enablement or it is stillattaching. 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.
Outcomes
- Declined purchases hold nothing and move nothing. They are recorded as a card transaction with
status: declinedand adecline_reason, and never change after that. - Refunds are usually a new card transaction on the same card, with
status: returned. The original purchase stayscleared, and the refund is not linked to it.returned_amountsays how much was refunded, andrefund_statereports 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. They arrive with
status: force_postedand noauth_amount.
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, and Dakota recovers the gap as the wallet is funded again. The wallet balance is never shown as negative. While a wallet owes Dakota money, for a gap like this or after a lost dispute, its cards can showoverdrawn, and creating or activating a card on it returns 409 wallet-owes-card-debt. See Card status.
Read the gap from each card transaction’s outstanding_amount: the part of cleared_amount that no authorization covered, less any refunds. The wallet-level outstanding figure is reserved for the wallet’s total shortfall, and currently always reports 0.00.
Reading transactions
Every stage arrives as a webhook: see Card transactions. To backfill or reconcile, useGET /card_transactions, filtered by customer_id, card_id, or cardholder_id, and GET /card_transactions/{card_transaction_id}.
