Skip to main content

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:

basisWhat it countsWhen
bankEvery transfer into the business's linked bank accounts, except those marked as not revenueAt 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​

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​

MethodPathWhat it returns
GET/revenue/accountThe business, its linked bank accounts (masked), the key's scopes and read_only
GET/revenue/eventsAmounts received, oldest first: basis, since, until, limit (≤ 500), after
GET/revenue/summaryTotals 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/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. 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.

View this page as Markdown