# List payments URL: https://docs.hanzo.ai/docs/openapi/tax/get-tax-payments > Returns the caller org's tax year as a PAYER: every payment it made to another org in that calendar year, on any rail, as the event plane records it, each classified — reportable or not, in which 1099 box, and the rule that decided it, with its source — and each payee's totals tested against the year's threshold. `GET /v1/tax/payments` > [Tax →](https://docs.hanzo.ai/docs/openapi/tax) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | -------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/tax/payments` | | **Method** | `GET` | | **Operation** | `get_tax_payments` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | Returns the caller org's tax year as a PAYER: every payment it made to another org in that calendar year, on any rail, as the event plane records it, each classified — reportable or not, in which 1099 box, and the rule that decided it, with its source — and each payee's totals tested against the year's threshold. The rules applied: a payment settled by a card or a third-party settlement network is reported on Form 1099-K by the settlement entity, not here; a payment for merchandise is not reported; a payment to a corporation is generally not reported, except for legal services; a payment in a digital asset is reported at its fair market value on the date paid; a box is reported only at or above the year's threshold — $600 through 2025, $2,000 for 2026 under P.L. 119-21, and not guessed for a year the IRS has not yet published. A payee's classification comes only from a W-9 it granted the caller; without one, nothing establishes an exemption. Org admins only. It reads; it prepares nothing and files nothing. ## Request 1 field. | Field | In | Type | Required | Description | | ------ | ----- | ------- | -------- | --------------------------------------------------------------- | | `year` | query | integer | — | Year is the calendar year the payments were made in, e.g. 2026. | ## Response | Status | Body | Meaning | | --------- | --------------- | ------- | | `200` | tax.Ledger | ok | | `default` | problem-details | refused | `200` body — 35 fields. | Field | In | Type | Always | Description | | ----------------------------------------- | ---- | ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- | | `payees` | body | tax.PayeeYear\[] | — | Payees is every org the caller paid, by org id. | | `payees[].category` | body | string | — | Category is what the payer states it bought from this payee; services when it has stated nothing. | | `payees[].lines` | body | tax.Line\[] | — | Lines are the payments, oldest first. | | `payees[].lines[].amountCents` | body | integer (int64) | — | AmountCents is its fair market value in U.S. dollars on the date paid, in cents — for a U.S. dollar payment, what was paid. | | `payees[].lines[].id` | body | string | — | ID is the economic event's id. | | `payees[].lines[].memo` | body | string | — | Memo is what was bought, in the rail's words. | | `payees[].lines[].paid` | body | integer (int64) | — | Paid is when, unix seconds. | | `payees[].lines[].proof` | body | string | — | Proof is the rail's own reference for the payment. | | `payees[].lines[].rail` | body | string | — | Rail is how it moved: x402, ledger, chain, ach, wire, card, network or other. | | `payees[].lines[].verdict` | body | tax.Verdict | — | | | `payees[].lines[].verdict.box` | body | tax.Box | — | | | `payees[].lines[].verdict.box.box` | body | string | — | | | `payees[].lines[].verdict.box.kind` | body | string | — | | | `payees[].lines[].verdict.box.label` | body | string | — | | | `payees[].lines[].verdict.reportable` | body | boolean | — | | | `payees[].lines[].verdict.rules` | body | tax.Rule\[] | — | Rules are every rule that applied, in the order applied — the last one is the verdict's reason. | | `payees[].lines[].verdict.rules[].code` | body | string | — | Code is the rule's stable name, for a caller that branches on it. | | `payees[].lines[].verdict.rules[].reason` | body | string | — | Reason is the rule, stated. | | `payees[].payee` | body | string | — | Payee is the org paid. | | `payees[].totals` | body | tax.Total\[] | — | Totals are the reportable sums by box. | | `payees[].totals[].amountCents` | body | integer (int64) | — | AmountCents is the reportable payments in this box, summed exactly and then rounded to cents. | | `payees[].totals[].box` | body | tax.Box | — | | | `payees[].totals[].box.box` | body | string | — | | | `payees[].totals[].box.kind` | body | string | — | | | `payees[].totals[].box.label` | body | string | — | | | `payees[].totals[].payments` | body | string\[] | — | Payments are the ids that sum into it. | | `payees[].totals[].reportable` | body | boolean | — | Reportable is true when the total is at or above the threshold. | | `payees[].totals[].rule` | body | tax.Rule | — | | | `payees[].totals[].rule.code` | body | string | — | Code is the rule's stable name, for a caller that branches on it. | | `payees[].totals[].rule.reason` | body | string | — | Reason is the rule, stated. | | `payees[].totals[].thresholdCents` | body | integer (int64) | — | ThresholdCents is the year's threshold for this box. | | `payees[].w9` | body | string | — | W9 is where the payer's W-9 request to this payee stands: none, requested, granted, declined or revoked. | | `source` | body | string | — | Source names where the year's numbers were read. | | `thresholdCents` | body | integer (int64) | — | ThresholdCents is the §6041(a) threshold for the year. | | `year` | body | integer (int64) | — | Year is the tax year. | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** `hanzo` has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK. **SDK** **.ts** ```ts import { Configuration, TaxApi } from 'hanzoai'; const api = new TaxApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.getTaxPayments(); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import TaxApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = TaxApi(client).get_tax_payments() ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.TaxAPI.GetTaxPayments(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, tax_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = tax_api::get_tax_payments(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.TaxApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new TaxApi(client).getTaxPayments(); ``` **HTTP** ```bash curl https://api.hanzo.ai/v1/tax/payments \ -H "Authorization: Bearer $HANZO_API_KEY" ``` **MCP** MCP reaches **tax** through the `tax` tool, which names its 26 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them: ```bash curl -X POST https://api.hanzo.ai/v1/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "describe", "arguments": { "op": "list_tax_filings" } } }' ``` --- [Tax API](https://docs.hanzo.ai/docs/openapi/tax) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)