> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dakota.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Funding

> How a purchase holds, clears, and settles against the wallet's available balance

<Warning>
  **Cards is available in sandbox only while we finish development.** Dakota enables Cards per
  account. The Cards endpoints are in the [API reference](/api-reference/introduction), marked
  **Sandbox only**. Endpoints, fields, and flows can still change before release.
</Warning>

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](/documentation/cards/wallet-enablement).

## A purchase, end to end

```mermaid theme={null}
sequenceDiagram
    participant M as Merchant
    participant D as Dakota
    participant W as Customer wallet
    participant App as Your application

    M->>D: Authorization request
    D->>D: Check card status, spend limit, available balance
    D->>W: Place a hold
    D-->>M: Approved
    D--)App: webhook card_transaction.created (authorized)
    M->>D: Clearing, hours or days later
    D->>W: Release the hold, settle the cleared amount
    D--)App: webhook card_transaction.updated (cleared)
```

* **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`](/api-reference/wallets/get-wallet-balances-across-all-networks) returns the four figures in a `card` object:

```json theme={null}
{
  "card": {
    "currency": "USD",
    "total": "1250.00",
    "held": "42.50",
    "outstanding": "0.00",
    "available": "1207.50"
  }
}
```

| Figure | Meaning |
| - | - |
| `total` | The wallet's confirmed balance of the spend asset. It can trail the chain by a few minutes. |
| `held` | Uncleared card holds, plus wallet sends still in flight. |
| `outstanding` | Settled card spend the wallet could not cover. Rare. |
| `available` | `total − held − outstanding`, never below zero. Show this one to the cardholder. |

* 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

```mermaid theme={null}
flowchart TD
    A["authorized<br/><i>hold placed</i>"]
    A -->|merchant captures| C["cleared"]
    A -->|captured in parts| PC["partially_cleared"]
    A -->|merchant cancels| R["auth_reversed<br/><i>hold released</i>"]
    A -->|never captured| E["expired<br/><i>hold released</i>"]
```

* **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](/documentation/cards/webhooks#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](/documentation/cards/webhooks#card-transactions). To backfill or reconcile, use [`GET /card_transactions`](/api-reference/cards/list-card-transactions), filtered by `customer_id`, `card_id`, or `cardholder_id`, and [`GET /card_transactions/{card_transaction_id}`](/api-reference/cards/get-a-card-transaction).