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

# Earnings

> Your share of every settled transaction — and the REST feed to reconcile it

Your organization earns a share of **every settled transaction** on your program — currently 1% — on both funding models, in live and test mode alike. Nothing to enable: the share books automatically at settlement.

## How earnings book

Earnings are an append-only ledger. Rows are never mutated — a correction is always a new row — so a cursor walk never misses an adjustment:

* **`interchange_accrual`** — a charge settled; `amount_cents` (positive) is your share of it.
* **`interchange_reversal`** — a refund or return settled; `amount_cents` (negative) claws back exactly the share of the refunded amount. Partial refunds reverse partial shares.
* **`payout`** — accrued earnings were paid out (negative, no underlying network transaction). Earnings accrue as bookkeeping and pay out as USDC to your [company pool](/companies/wallet-funding/company-wallet) address, where the deposit also shows on the pool feed.

<Note>
  Refunds arrive in two shapes, and the reversal row's `transaction_id` tells them apart. A **standalone refund** is its own transaction on the network — its row carries the *refund's* id and `transaction_amount_cents` (negative); correlate to the original via `card_id`, `merchant`, or your order mapping. An **in-place refund** (the charge itself flips to refunded) mirrors its accrual exactly — its row carries the *original charge's* id, so it joins straight back to the accrual, and `transaction_amount_cents` is `null`. The same network doctrine drives [`transaction.cleared`](/companies/webhooks#transaction-cleared) refunds and [`reward.reversed`](/companies/webhooks#reward-reversed).
</Note>

If you also use [markup](/companies/webhooks) or Tokenback features, their rows (`commerce_markup_accrual`, `funding_markup_accrual`, `commerce_markup_reversal`, `token_share_routed`, `token_share_reversal`) appear in the same feed; they key on internal ids, so their `transaction_id` is `null`.

Earnings are separate from [Tokenback routing](/companies/webhooks#reward-earned): `reward_share_bps` routes a slice of *your* share onward to the purchasing user as tokens (at `0`, you keep all of it, and no `reward.*` events fire).

## The reconciliation feed

`GET /api/v1/wallet/earnings` returns the ledger newest-first, scoped to your org and your credential's mode:

```bash theme={null}
curl "https://api.agentcard.sh/api/v1/wallet/earnings?limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "oe_31f...",
      "object": "earning",
      "kind": "interchange_reversal",
      "amount_cents": -10,
      "currency": "usd",
      "transaction_id": "txn_refund_8842",
      "transaction_amount_cents": -1000,
      "payment_id": "pay_...",
      "card_id": "card_...",
      "merchant": "COFFEE SHOP #42",
      "occurred_at": "2026-08-10T18:40:00.000Z",
      "livemode": true
    },
    {
      "id": "oe_2c9...",
      "object": "earning",
      "kind": "interchange_accrual",
      "amount_cents": 25,
      "currency": "usd",
      "transaction_id": "txn_8841",
      "transaction_amount_cents": 2500,
      "payment_id": "pay_...",
      "card_id": "card_...",
      "merchant": "COFFEE SHOP #42",
      "occurred_at": "2026-08-10T18:12:00.000Z",
      "livemode": true
    }
  ],
  "has_more": false
}
```

* `transaction_id` is the settled transaction's provider id — the same anchor `transaction.cleared` and `reward.earned` carry, so one key joins earnings, transactions, and rewards. It is `null` only on `payout` rows.
* `transaction_amount_cents` is the underlying settled (or refunded, negative) amount, so you can recompute the share or drive your own reward math without a second lookup.
* Filter with `?kind=interchange_accrual|interchange_reversal|payout`; paginate with `?limit=` (max 100) and `?starting_after=<row id>`.
* Rows exist for test-mode settlements too (`livemode: false` under a test credential) — [simulated charges](/companies/testing#simulate-transactions) accrue the same way, so the reconciliation loop is rehearsable end to end.

The dashboard's **Earnings** page renders this same ledger with a running total, and includes pending (authorized-but-unsettled) estimates the API deliberately omits — reconciliation is about booked rows.