fees.json: publish your fee schedule where agents can read it

Version 0.1, 2026-10-30. Open: anyone may implement it; no permission or fee needed.

AI agents now ask what it costs to get paid through a given provider. Today they scrape pricing pages, which change layout, block bots and mix plans together. A provider that hosts one small JSON file states its own fees in a form every agent reads the same way, with the date they took effect.

Where

Serve the file at https://<your-domain>/.well-known/fees.json with content-type: application/json and access-control-allow-origin: *. One file per domain. If you price differently by country, add one object per country to fees.

Shape

The top-level object has these fields:

• spec: always "https://paidrouter.com/spec/fees-json".
• version: "0.1".
• provider: your public name.
• updated: the date you last edited the file (YYYY-MM-DD).
• fees: a list of fee objects, one per way of getting paid.

Each fee object has these fields:

• platform (required): a short lowercase id for you, such as stripe, square or melio.
• method (required): the way of getting paid. Use these ids where they fit: card_online, card_in_person, card_keyed, ach_debit, ach_received, ach_invoice, wire_received, business_profile, goods_and_services, receive_usd_local, withdraw_to_us_bank. Otherwise use your own snake_case id.
• percent (required): the percent of the payment amount. Write 2.9 for 2.9%, and 0 for no percentage.
• fixed (required): the fixed fee per payment, in currency. Use 0 when there is none.
• cap and min (optional): the most and the least one payment can cost, in currency.
• currency (optional): ISO 4217 code. Defaults to USD.
• country (optional): the ISO 3166 country where this price applies. Defaults to US.
• plan (optional): which plan the price belongs to, when it depends on one (for example free or plus).
• extras (optional): other charges that can apply. Each key is a name and each value is a number. A key ending in _percent is a percent of the payment; any other numeric key is a fixed amount in currency. Example: "international_card_percent": 1.5, "dispute_fee": 15.
• effective_date (required): the date this price took effect (YYYY-MM-DD). A future date announces a change.
• source (required): the URL of your human-readable pricing page that states the same price.
• note (optional): one plain sentence for a condition the numbers can't express.

A payment of amount A costs A × percent / 100 + fixed, raised to min and lowered to cap when those are set. Extras are added only when their condition applies.

Example

{
  "spec": "https://paidrouter.com/spec/fees-json",
  "version": "0.1",
  "provider": "Example Pay",
  "updated": "2026-10-30",
  "fees": [
    { "platform": "examplepay", "method": "card_online", "percent": 2.9, "fixed": 0.30,
      "extras": { "international_card_percent": 1.5, "dispute_fee": 15 },
      "effective_date": "2026-01-01", "source": "https://examplepay.com/pricing" },
    { "platform": "examplepay", "method": "ach_debit", "percent": 0.8, "fixed": 0, "cap": 5,
      "effective_date": "2026-01-01", "source": "https://examplepay.com/pricing" }
  ]
}

How PaidRouter uses it

PaidRouter's weekly check looks for /.well-known/fees.json on each provider's domain. If an entry there has the same platform and method as ours, and the same percent, fixed, cap and min, our entry is marked provider_published: true in every answer. Agents then know the number is stated by the provider in machine-readable form, not only scraped from a page. If the numbers differ, we re-read the source page and fix whichever side is out of date. Ranking stays by fee only. Publishing the file never moves a provider up the list.

Versions

The spec is versioned. A field is never removed or redefined within a major version; new optional fields may be added.

Plain text: /spec/fees-json.md