# Revenue API

The Revenue API lets a business share **verified revenue**: money that actually reached its bank accounts. A third-party site gets a read-only key and reads it, the way Stripe or Polar keys are used. Examples are TrustMRR-style leaderboards, investors and marketplaces.

The site gets three things:

- **Who the key belongs to.** It also says whether the key can only read.
- **Every amount received**, oldest first, as far back as the history goes.
- **Totals by day or month.** These include the last 30 days, the figure leaderboards rank by when there is no subscription MRR.

## What counts as revenue {#basis}

Pick a `basis` on each call:

| `basis` | What it counts | When |
|---|---|---|
| `bank` | Every transfer **into** the business's linked bank accounts, except those marked as not revenue | At the time the bank booked it (`booked_at`) |
| `payments` (default) | Ha Tang VietQR payments that were paid, at the amount received (`paid_amount`) | At `paid_at` |

`bank` is the broadest figure. It counts money from any source: VietQR payments, direct transfers from customers, and payouts from a marketplace. `payments` is narrower: only payments created through Ha Tang.

Neither basis counts:

- **Outgoing transfers.**
- **Transfers marked as not revenue**, such as a refund received, a transfer between your own accounts or a loan. Mark them in the dashboard (**Payments → Invoice reconciliation → the transfer → Needs no invoice**), or with `POST /payments/transactions/{id}/invoice-exempt` and a reason. It is the same flag e-invoice reconciliation uses; undo it with `DELETE` on the same path.
- **App Store, Google Play and web subscriptions** recorded in the support CRM. Only money seen on the bank side counts.

Amounts are whole đồng (`VND`, no minor unit). Refunds paid back to customers are not linked to the original money yet, so they are not subtracted.

## How far back it goes {#history}

`bank` history starts with the oldest transfer Ha Tang has for the account:

- what the bank sent since the account was linked;
- the bank history Ha Tang re-reads;
- any **statement you import**.

To bring in older months, [import a statement](https://hatang.dev/docs/guides/payments/bank-connections.md#statement-import). `GET /revenue/summary` returns `totals.first_at`, the oldest amount on record, so a site can show how much history is verified.

## A read-only key {#key}

Create an API key with **only `payments:read`**: **API keys → Create → Payments: Read**. The key can read payments, transactions and revenue, and cannot change anything.

`GET /revenue/account` returns `read_only: true` for such a key. A site should refuse keys with `read_only: false`, as TrustMRR refuses Stripe secret keys.

Keys created in the dashboard read production. A development key (`ht_test_…`) reads the development environment; see [Environments](https://hatang.dev/docs/guides/payments/environments.md).

## Endpoints {#endpoints}

| Method | Path | What it returns |
|---|---|---|
| `GET` | `/revenue/account` | The business, its linked bank accounts (masked), the key's scopes and `read_only` |
| `GET` | `/revenue/events` | Amounts received, oldest first: `basis`, `since`, `until`, `limit` (≤ 500), `after` |
| `GET` | `/revenue/summary` | Totals by `interval` (`day` or `month`) between `from` and `to` in `tz` (default `Asia/Ho_Chi_Minh`), plus all-time, last-30-day and previous-30-day totals |

`/payments` and `/payments/transactions` also take date filters: `created_after` / `created_before` / `paid_after` / `paid_before`, and `booked_after` / `booked_before`.

```bash
curl "https://api.hatang.dev/revenue/events?basis=bank&since=2025-01-01&limit=500" \
  -H "Authorization: Bearer ht_…"
```

```json
{
  "object": "list",
  "data": [
    {
      "object": "revenue_event",
      "id": "ptx_…",
      "occurred_at": "2025-01-03T02:14:09.000Z",
      "amount": 1290000,
      "currency": "VND",
      "basis": "bank",
      "source": "bank_transfer",
      "description": "DH000123 thanh toan",
      "reference": "FT25003…",
      "counterparty": { "name": "NGUYEN VAN A", "account": null, "bank": "VCB" },
      "payment_id": null,
      "transaction_id": "ptx_…",
      "connection_id": "pbc_…"
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNS0wMS0wM1Qw…"
}
```

## Syncing {#sync}

- **First sync.** Call `GET /revenue/events` without `since`, or with the oldest date you want, and follow `next_cursor` until `has_more` is false.
- **Later syncs.** Ask again with `since` a few days before the last `occurred_at` you stored. Deduplicate by `id`, which is stable: the transaction id for `bank`, the payment id for `payments`. Statements can add older transfers at any time, so re-read a wider window now and then.
- **For a leaderboard figure,** `GET /revenue/summary` gives `totals.last_30_days` and `previous_30_days` without paging.
- **For new money as it arrives,** subscribe to the `transaction.received` and `payment.succeeded` [webhooks](https://hatang.dev/docs/guides/payments/webhooks.md). Managing webhooks needs a write key, so the business sets them up.

## With the Rust SDK {#rust}

The [`hatang` crate](https://hatang.dev/docs/guides/sdks/rust.md) has typed calls for the whole flow:

```rust
use hatang::{Hatang, RevenueBasis};

let hatang = Hatang::new(key_the_business_gave_you)?;
let account = hatang.revenue.account().await?;
if !account.read_only {
    return Err("use a key with only payments:read".into());
}
let events = hatang.revenue.events_since(RevenueBasis::Bank, Some("2025-01-01")).await?; // follows the cursor
let summary = hatang.revenue.summary(&Default::default()).await?;
println!("{}: {} đ in the last 30 days", account.business.name, summary.totals.last_30_days);
```

From any other language, call the endpoints above. See the [REST API reference](https://hatang.dev/docs/reference/api.md) for every field.

Source: https://hatang.dev/docs/guides/payments/revenue-api
