# Fluveo

> Fluveo is a payments processor with one /v1 API for every store. Card, Pix and Boleto are methods of one call, POST /v1/payment_intents. No server SDK: use plain HTTP. fluveo.js is not available in production yet.

Three ways to take a payment. Pick one:

- **Fluveo's page**: [hosted checkout](https://docs.fluveo.com/payments/checkout.md). Your server makes a Checkout Session and sends the buyer to a page Fluveo serves.
- **Your page, Fluveo's form**: [custom checkout](https://docs.fluveo.com/payments/custom-checkout.md). fluveo.js is not available in production yet.
- **Server only**: [PaymentIntents](https://docs.fluveo.com/payments/accept-a-payment.md). Your server makes and confirms the payment: a Pix, a Boleto or a card saved earlier.

Each merchant has its own account (`mch_...`) and keys; a checkout platform only holds that key. Every page has a Markdown copy at its URL plus `.md`; a page with code, a shorter one per language, such as `https://docs.fluveo.com/agents/integrate.python.md` (or `.curl.md`, `.node.md`, `.php.md`).

**Integrating Fluveo? Start with [the integration playbook for agents](https://docs.fluveo.com/agents/integrate.md).** It goes from test key to verified payment, webhook and refund. [Ready prompts](https://docs.fluveo.com/agents/prompt.md) are for people to paste.

The Fluveo MCP server is not available in production yet.

API base: `https://api.fluveo.com/v1`. API version: `2026-05-27.dahlia`, the only one ([versions.json](https://docs.fluveo.com/versions.json)). Every operation Fluveo serves is in [openapi.json](https://docs.fluveo.com/openapi.json).

One path to charge: `POST /v1/payment_intents`. Card and Pix differ only in `payment_method_types[]` and `payment_method` or `payment_method_data`. Use a currency the account accepts and the method charges in ([methods table](https://docs.fluveo.com/payments.md#payment-methods)). A card answers `succeeded`, a Pix `requires_action` with `next_action.pix_display_qr_code`.

```bash
# A card. A Pix sends the pix fields of the JavaScript below in place of the card ones.
curl https://api.fluveo.com/v1/payment_intents -H "Authorization: Bearer $FLUVEO_SECRET_KEY" \
  -H "Idempotency-Key: order-1042-pay" -d amount=2000 -d currency=usd \
  -d "payment_method_types[]=card" -d payment_method=pm_card_visa -d confirm=true
```

```javascript
const METHODS = {
  card: { currency: "usd", "payment_method_types[]": "card", payment_method: "pm_card_visa" },
  pix: { currency: "brl", "payment_method_types[]": "pix", "payment_method_data[type]": "pix",
    "payment_method_data[billing_details][name]": "Ada Lima", "payment_method_data[billing_details][email]": "ada@example.com",
    "payment_method_data[billing_details][phone]": "+5511999999999", "payment_method_data[billing_details][tax_id]": "12345678909" },
};
const response = await fetch("https://api.fluveo.com/v1/payment_intents", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.FLUVEO_SECRET_KEY}`, "Idempotency-Key": "order-1042-pay" },
  body: new URLSearchParams({ amount: "2000", ...METHODS.card, confirm: "true" }),
});
```

ALWAYS:

- Call the API from your server over plain HTTP (curl, fetch, requests, PHP curl) with form-encoded bodies.
- Send `Authorization: Bearer <secret key>`. Build and test with `sk_test_` keys only, read from an environment variable.
- Send an `Idempotency-Key` (1 to 255 characters) on every POST, one per business action. On a retry, send the same key with the same body.
- Read the webhook's raw body, check `Fluveo-Signature` (HMAC-SHA256 of `t.body`, keyed by the `whsec_` secret), reject old timestamps, skip handled event ids.
- Fulfil an order only on a verified success event, such as `payment_intent.succeeded`.
- Write amounts in the smallest currency unit: `2000` is $20.00 in `usd` and R$ 20,00 in `brl`.
- Fulfil a Pix or a Boleto only on its success event: it is never paid at create time.
- Treat ids as opaque strings.

NEVER:

- Never install a server SDK for payments or call another payments API host. fluveo.js is not available in production yet.
- Never build a card input or read or send a card number: the payment form takes the card. Server-only test payments use test PaymentMethods such as `pm_card_visa`.
- Never send a header that acts for another account, `transfer_data`, `on_behalf_of` or `application_fee_amount`. Fluveo refuses each with a 400 that names it.
- Never send a `Fluveo-Version` header: every request runs in `2026-05-27.dahlia`, the only version. Another version gets a 400 `invalid_request_error`.
- Never use an endpoint or parameter because another payments API has it. If it is not in openapi.json, it does not exist here.
- Never put a `sk_` or `whsec_` secret in code, a commit, a log or a browser; a page gets only `pk_test_`. Never use a live key without a person's approval.
- Never fulfil on the browser redirect after payment: the return page only thanks the buyer.

## Build a custom checkout

Read [custom-checkout.txt](https://docs.fluveo.com/llms/custom-checkout.txt) first: the whole task in one file, under 40 KB. The form's options and events, with the errors they throw, are in [payment-element.txt](https://docs.fluveo.com/llms/payment-element.txt).

## Overview

- [Fluveo documentation](https://docs.fluveo.com/index.md): Take card, Pix and Boleto payments through one /v1 API, with the same calls for every store.
- [Changelog](https://docs.fluveo.com/changelog.md): Dated changes to the Fluveo API and to these docs, newest first.
- [Support](https://docs.fluveo.com/support.md): How to get help with your Fluveo integration or your account.

## Get started

- [Quickstart](https://docs.fluveo.com/start.md): Go from a test secret key to your first successful test payment in a few minutes, with plain HTTP.
- [Authentication](https://docs.fluveo.com/start/authentication.md): Authenticate with a secret or restricted key, give each platform its own named key, and read the errors a key can get.
- [Testing](https://docs.fluveo.com/start/testing.md): What test mode does, how each test card ends, and what a test Pix or Boleto does.
- [Idempotency](https://docs.fluveo.com/start/idempotency.md): Retry any POST with the Idempotency-Key header so it never charges twice, and see how an unknown result ended.
- [Pagination](https://docs.fluveo.com/start/pagination.md): Page lists with limit, starting_after and ending_before, and filter by creation time.
- [Expanding responses](https://docs.fluveo.com/start/expand.md): Ask for a related object in the same answer with expand[], instead of making a second request.
- [Metadata](https://docs.fluveo.com/start/metadata.md): Put your own key-value pairs, such as an order number, on objects; change or remove them.
- [Versioning](https://docs.fluveo.com/start/versioning.md): Fluveo serves one API version, 2026-05-27.dahlia. Send no Fluveo-Version header.
- [Deprecation policy](https://docs.fluveo.com/start/deprecation.md): Which API changes need a new version, which do not, and where each change is listed.

## Payments

- [Payments](https://docs.fluveo.com/payments.md): One /v1 API for every store: card, Pix and Boleto are payment methods of the same PaymentIntent.
- [Accept a payment](https://docs.fluveo.com/payments/accept-a-payment.md): One call for card, Pix and Boleto; only the currency and the payment method fields change.
- [Cards](https://docs.fluveo.com/payments/cards.md): Take card payments with one API: how a payment moves, brands, 3D Secure, holds and declines.
- [Capture or cancel](https://docs.fluveo.com/payments/capture-and-cancel.md): Hold an amount on a card, capture all or part of it later, or cancel the payment.
- [Apple Pay](https://docs.fluveo.com/payments/apple-pay.md): Turn on Apple Pay, register your site and pay as a card with a token of the buyer's data.
- [Pix](https://docs.fluveo.com/payments/pix.md): Create a Pix, show its code, and fulfil on payment_intent.succeeded.
- [Boleto](https://docs.fluveo.com/payments/boleto.md): Issue a Boleto, show its line and PDF, and learn when it is paid or expires. No refunds.
- [Customers](https://docs.fluveo.com/payments/customers.md): Keep a buyer as a Customer: create, find, update and delete it, and store its tax IDs.
- [Save a card](https://docs.fluveo.com/payments/save-a-card.md): Save a card with a SetupIntent and charge it later, with the buyer away.
- [Hosted checkout](https://docs.fluveo.com/payments/checkout.md): Send the buyer to a Fluveo page that takes the payment.
- [Payment Element](https://docs.fluveo.com/payments/payment-element.md): The payment form: its methods, layouts, look and options.
- [Custom checkout](https://docs.fluveo.com/payments/custom-checkout.md): Take a card on your own page with Fluveo's payment form.
- [fluveo.js](https://docs.fluveo.com/payments/fluveo-js.md): Every call, option, event and result.
- [Appearance](https://docs.fluveo.com/payments/fluveo-js-appearance.md): The payment form's themes and variables.
- [fluveo.js errors](https://docs.fluveo.com/payments/fluveo-js-errors.md): Each integration error, and its fix.
- [Payment links](https://docs.fluveo.com/payments/payment-links.md): Create a link that sells your Prices, share it, switch it off and read its payments.
- [Refund a payment](https://docs.fluveo.com/payments/refunds.md): Refund a card or Pix payment in full or in part, and follow it to the end. Boleto has no refunds.
- [Handle disputes](https://docs.fluveo.com/payments/disputes.md): Find card disputes, send evidence, or accept them.
- [Balance and payouts](https://docs.fluveo.com/payments/payouts.md): Read your balance, see your statement, and pay out to your bank.
- [Reserves](https://docs.fluveo.com/payments/reserves.md): Read what part of your sales is held back, why, and when each amount is released.

## Catalog

- [Products](https://docs.fluveo.com/catalog/products.md): Keep what you sell as Products with prices, then archive, delete or search them.
- [Prices](https://docs.fluveo.com/catalog/prices.md): Set how much a Product costs, and find prices by lookup key or search.

## Webhooks

- [Receive webhooks](https://docs.fluveo.com/webhooks.md): Get a signed call from Fluveo each time something happens in your account, check it, and act on it.
- [Check webhook signatures](https://docs.fluveo.com/webhooks/signatures.md): Prove that a webhook came from Fluveo and was not changed, with a few lines of code and no SDK.
- [Event types](https://docs.fluveo.com/webhooks/events.md): Every event type Fluveo sends to webhook endpoints, when it is sent and the object it carries.
- [Test webhooks](https://docs.fluveo.com/webhooks/testing.md): Receive test events on your own computer and make Fluveo send each event type with test API calls.

## Dashboard

- [Payment links (dashboard)](https://docs.fluveo.com/dashboard/payment-links.md): Create, share and track payment links from the Dashboard.
- [Products (dashboard)](https://docs.fluveo.com/dashboard/products.md): Add products and their prices, archive or delete them, and search your catalog from the dashboard.
- [Request logs](https://docs.fluveo.com/dashboard/request-logs.md): See each API call your store made, what it sent and got, and open a failed call's log.

## Platforms

- [Platforms and checkouts](https://docs.fluveo.com/platforms.md): How a checkout platform sends payments to Fluveo with each merchant's own Fluveo key.
- [Shopify](https://docs.fluveo.com/platforms/shopify.md): There is no Shopify integration for Fluveo today.
- [WooCommerce](https://docs.fluveo.com/platforms/woocommerce.md): There is no WooCommerce plugin for Fluveo today.

## Build with AI agents

- [Build with AI agents](https://docs.fluveo.com/agents.md): What Fluveo gives AI coding agents so they can integrate it alone, and what a person still does by hand.
- [Integrate Fluveo with an AI agent](https://docs.fluveo.com/agents/integrate.md): The playbook an AI agent follows in test mode, from the key to a verified payment, webhook and refund.
- [Ready prompts for your coding agent](https://docs.fluveo.com/agents/prompt.md): Prompts for Claude Code, Cursor or Codex that build a Fluveo checkout or server integration and prove it.
- [Fluveo MCP](https://docs.fluveo.com/agents/mcp.md): A remote MCP server that lets an AI client read and change your test store.
- [Connect to Fluveo MCP](https://docs.fluveo.com/agents/mcp/connect.md): Add Fluveo MCP to Claude Code, Cursor, Codex, VS Code or any client.
- [MCP authentication](https://docs.fluveo.com/agents/mcp/authentication.md): Make an agent key for Fluveo MCP, choose what it may do, and revoke it.
- [MCP sign-in with OAuth](https://docs.fluveo.com/agents/mcp/oauth.md): Sign in from an AI client, choose what it may do, revoke it.
- [MCP tools](https://docs.fluveo.com/agents/mcp/tools.md): Every Fluveo MCP tool, and what an agent key may do on each API operation.
- [Agent approvals](https://docs.fluveo.com/agents/mcp/approvals.md): Which agent requests wait for a person, and how the agent retries.
- [MCP security](https://docs.fluveo.com/agents/mcp/security.md): What protects your store when an AI agent holds a key, and what it never sees.

## API reference

- [API reference](https://docs.fluveo.com/api.md): Every operation of the Fluveo /v1 API, generated from the code: parameters, examples, errors and events. Preview marks what is not locked yet. It links one page per object (21 pages), such as https://docs.fluveo.com/api/payment_intents.md.
- [Errors](https://docs.fluveo.com/errors.md): Every error the Fluveo API returns: its code, HTTP status, message and what to do.
- [Permissions](https://docs.fluveo.com/permissions.md): What each restricted key permission allows, and the permission every operation needs.
- [Search](https://docs.fluveo.com/search.md): The query fields of each search operation, and the language its query takes.
- [OpenAPI](https://docs.fluveo.com/openapi.json): every operation Fluveo serves; what is not in it does not exist
- [API version](https://docs.fluveo.com/versions.json): the one API version Fluveo serves

## Optional

- [Every page in one file](https://docs.fluveo.com/llms-full.txt): all pages, for a long context