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
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-exemptand a reason. It is the same flag e-invoice reconciliation uses; undo it withDELETEon 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
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. 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
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.
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.
curl "https://api.hatang.dev/revenue/events?basis=bank&since=2025-01-01&limit=500" \
-H "Authorization: Bearer ht_…"
{
"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
- First sync. Call
GET /revenue/eventswithoutsince, or with the oldest date you want, and follownext_cursoruntilhas_moreis false. - Later syncs. Ask again with
sincea few days before the lastoccurred_atyou stored. Deduplicate byid, which is stable: the transaction id forbank, the payment id forpayments. Statements can add older transfers at any time, so re-read a wider window now and then. - For a leaderboard figure,
GET /revenue/summarygivestotals.last_30_daysandprevious_30_dayswithout paging. - For new money as it arrives, subscribe to the
transaction.receivedandpayment.succeededwebhooks. Managing webhooks needs a write key, so the business sets them up.
With the Rust SDK
The hatang crate has typed calls for the whole flow:
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 for every field.