> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fluveo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fluveo.com/_mcp/server.

# Changelog

What's new in the Fluveo `/v1` API and these docs.

## Behavior change: dispute test PaymentMethods are refused on Brazilian accounts

**Behavior change.** This changes what test mode answers on a Brazilian (BRL)
account.

* On a Brazilian account in test mode, the dispute test PaymentMethods
  (`pm_card_createDispute` and the other names of Stripe's dispute table) are
  now refused at once on PaymentIntent create and confirm and on SetupIntent
  confirm, with HTTP 400 `invalid_request_error`, `code`
  `payment_method_not_available` and `param` `payment_method`. No payment is
  made. Before, the payment could succeed without a dispute or stay
  `processing`.
* Test mode cannot simulate a dispute on a Brazilian account: disputes there
  come only from the acquirer, after a real chargeback. To test disputes, use a
  US test account, where `pm_card_createDispute` still opens one.
* On a Brazilian account the other test PaymentMethods give the acquirer's test
  result for the card number's last digit, not Stripe's documented outcome.
  `pm_card_mastercard` pays. The [Testing guide](/guides/testing#brazilian-brl-accounts)
  lists the rules and the cards to avoid.
* US accounts and live mode are unchanged.

## Behavior change: Checkout Session metadata stays on the session

**Behavior change.** This changes what Checkout Sessions created with your
secret key send to the PaymentIntent.

* A Checkout Session's `metadata` now stays on the session, as on Stripe. It is
  no longer copied to the session's PaymentIntent, so it no longer shows on that
  PaymentIntent or its Charges. Retrieving, listing and updating the session
  still show and change it, and updating the session no longer changes the
  PaymentIntent (or the other way round). Sessions created before this change
  keep their copied keys.
* If you read metadata from the PaymentIntent, send it in
  `payment_intent_data[metadata]` when you create the session.
* `payment_intent_data[metadata]` takes at most **31 keys** (Stripe allows 50;
  Fluveo and the payment processor reserve up to 19 keys on the PaymentIntent).
  Updates of that PaymentIntent keep the same limit. An older PaymentIntent that
  already has more than 31 keys can change or remove keys, but an update can
  never leave it with more keys than it had.
* These keys in `payment_intent_data[metadata]` are refused with a `400`: an
  `order_id` key (any letter case), an `invoice` key, an empty key, and a key
  with `[` or `]`. `metadata[order_id]` and `metadata[invoice]` on the session
  itself are still fine.
* See [Checkout Sessions](/checkout/checkout-sessions) for the full rules.

## Internal webhook delivery machinery

* Internal fan-out, signature, retry, and redaction machinery was implemented
  behind the platform boundary.
* It is not a merchant-public contract: WebhookEndpoints and Events remain
  unavailable until state and queries are owned by Fluveo merchant (`mch_*`) and
  pass blocking cross-tenant tests.
* The event-type pages now describe implementation evidence, not a public
  subscription or delivery promise.

## Webhook and Event platform groundwork

* Internal/platform WebhookEndpoint management, Event projection, and signing
  helpers were introduced.
* Subsequent contract reconciliation keeps `/v1/webhook_endpoints` and
  `/v1/events` unavailable for merchant-public keys. These handlers are not in
  the generated API Reference or SDK certification.
* Client signature helpers remain available for isolated payload-verification
  tests; manager method presence does not imply server availability.

## SDKs and developer docs

* **Experimental clients** (Node, Python, Go) — Stripe-shape resource clients,
  `Idempotency-Key` propagation, and HMAC-SHA256 webhook helpers. Unpublished;
  Fluveo does not offer SDKs yet.
* **Getting-started docs**: [Quickstart](/quickstart),
  [Authentication](/authentication), [Webhooks](/webhooks), and [Errors](/errors).
* An interactive [API Reference](/api-reference) generated directly from the
  canonical OpenAPI contract, plus an honest [API coverage](/api-coverage) map
  (8 live resources, 17 planned).

## Balance and balance transactions

* `GET /v1/balance` returns the merchant's `available` and `pending` funds by
  currency, backed by the TigerBeetle ledger.
* `GET /v1/balance_transactions` lists money-moving events (charges, refunds,
  fees, payouts) with cursor pagination and a real `has_more`. See
  [Paginate balance transactions](/cookbooks/paginate-balance-transactions).

## Stripe-compatible /v1 launch API

* The `/v1` surface went live: **Payment Intents** (create → confirm → capture →
  cancel), **Customers**, **Refunds**, and read-only **Charges** — Stripe-shape
  requests and responses, secret-key auth, and `application/x-www-form-urlencoded`
  bodies.
* See [Migrate from Stripe](/guides/migrate-from-stripe) to point an existing
  integration at Fluveo with two changes.