---
title: "Payments"
description: "One /v1 API for every store: card, Pix and Boleto are payment methods of the same PaymentIntent."
url: https://docs.fluveo.com/payments/
---

> Index of every page: https://docs.fluveo.com/llms.txt. Integrating Fluveo? Read https://docs.fluveo.com/agents/integrate.md first.

> Too long? This page with code in one language only: https://docs.fluveo.com/payments.curl.md (cURL), https://docs.fluveo.com/payments.node.md (Node.js), https://docs.fluveo.com/payments.python.md (Python), https://docs.fluveo.com/payments.php.md (PHP).

# Payments

One /v1 API for every store: card, Pix and Boleto are payment methods of the same PaymentIntent.

Every Fluveo store takes payments the same way: one secret key, one `/v1` API, one set of webhooks. You create a PaymentIntent with `POST /v1/payment_intents`, pick the payment method, and Fluveo tells you by webhook when the money is in. Card, Pix and Boleto are payment methods of that same call, not separate products. Fluveo processes every payment itself and shows you the result as its own objects.

## What you can do

- [Accept a payment](https://docs.fluveo.com/payments/accept-a-payment.md): One call for card, Pix and Boleto. Confirm, handle 3D Secure, capture now or later.
- [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.
- [Customers](https://docs.fluveo.com/payments/customers.md): Keep a buyer on file with contact details and tax IDs.
- [Save a card](https://docs.fluveo.com/payments/save-a-card.md): Keep a buyer's card on file and charge it while they are away.
- [Apple Pay](https://docs.fluveo.com/payments/apple-pay.md): Turn a buyer's Apple Pay approval into a card token and pay with it like any card.
- [Hosted checkout](https://docs.fluveo.com/payments/checkout.md): Create a Checkout Session and send the buyer to a Fluveo page that takes the card.
- [Custom checkout](https://docs.fluveo.com/payments/custom-checkout.md): Keep your own checkout page and put Fluveo's payment form in it.
- [Payment Element](https://docs.fluveo.com/payments/payment-element.md): See what the payment form shows, and set its layout, its look and its options.
- [Payment links](https://docs.fluveo.com/payments/payment-links.md): Share one link that sells your Prices to any buyer who opens it.
- [Refund a payment](https://docs.fluveo.com/payments/refunds.md): Give back all or part of a paid payment.
- [Handle disputes](https://docs.fluveo.com/payments/disputes.md): Learn when a buyer disputes a card payment, then send evidence or accept it.
- [Balance and payouts](https://docs.fluveo.com/payments/payouts.md): See what your account holds and send it to your bank.
- [Reserves](https://docs.fluveo.com/payments/reserves.md): See how much of your sales is held back and when it comes back.

## Payment methods

A PaymentIntent's `currency` is a currency your account accepts; `default_currency` on `GET /v1/account` names one. Any other answers a 400 on `currency`. Each method charges in the currencies of this table:

| Method | Currencies | What the buyer does | When you know it is paid | Refunds |
| --- | --- | --- | --- | --- |
| [Card](https://docs.fluveo.com/payments/cards.md) | `usd`, `brl` | Enters the card on a Fluveo page, in Fluveo's form on your own page, or in a checkout that sends it to Fluveo, never to your server | In the confirm response, or after 3D Secure | Yes, full or partial |
| [Pix](https://docs.fluveo.com/payments/pix.md) | `brl` | Scans a QR code or pastes a code in their bank app | As soon as the bank tells Fluveo | Yes, full or partial, up to 90 days after payment |
| [Boleto](https://docs.fluveo.com/payments/boleto.md) | `brl` | Pays a bank slip by its line or its PDF, up to the due date | When the bank confirms the payment | No |

A Pix or a Boleto is paid after your call returns. The PaymentIntent waits in `requires_action` while the buyer pays, and a webhook tells you whether it succeeded or expired. Never fulfil an order from the response of the create call.

## How the pieces fit

| Object | Id prefix | What it is |
| --- | --- | --- |
| PaymentIntent | `pi_` | One payment from a buyer, from creation to its final state. |
| Charge | `ch_` for a card, `py_` for a Pix or a Boleto | One attempt to move money. A PaymentIntent points to its newest one in `latest_charge`. |
| Refund | `re_` | Money sent back to the buyer for a charge. |
| Dispute | opaque | A buyer's challenge of a card charge with their bank. Store the id as you got it; never parse it. |
| Balance | none | What your account holds now, in `available` and `pending`. |
| Balance transaction | `txn_` | One line of your statement: a charge, a refund, a payout. |
| Payout | `po_` | A transfer of available money out to your bank. |
| Event | `evt_` | Something that happened to one of the objects above, sent to your webhook endpoint. |

Every amount is an integer in the smallest unit of the currency: `2000` is $20.00 in `usd`, and `1000` is R$ 10,00 in `brl` (centavos).

## Where your money is

Money from a payment lands in your balance as `pending` and turns `available` later. `GET /v1/balance` returns both amounts, and a payout takes available money out to your bank. Fluveo is where you read and move it. See [Balance and payouts](https://docs.fluveo.com/payments/payouts.md) for when money becomes available and which bank account receives it.

**Read your balance**

cURL:

```bash
curl https://api.fluveo.com/v1/balance \
  -H "Authorization: Bearer sk_test_..."
```

Node.js:

```javascript
const response = await fetch("https://api.fluveo.com/v1/balance", {
  headers: { Authorization: "Bearer sk_test_..." },
});
console.log(await response.json());
```

Python:

```python
import requests

response = requests.get(
    "https://api.fluveo.com/v1/balance",
    headers={"Authorization": "Bearer sk_test_..."},
)
print(response.json())
```

PHP:

```php
<?php
$ch = curl_init("https://api.fluveo.com/v1/balance");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."],
]);
echo curl_exec($ch);
```

## What Fluveo controls for you

Fluveo sets the routing and its fees on every payment. These are refused with a 400 that names the field or the header, so do not send them:

- a header that acts for another account: each merchant uses its own key;
- `transfer_data`, `transfer_group`, `on_behalf_of`, `application_fee_amount` and other routing fields;
- raw card numbers in `payment_method_data[card]` or `card`. Use a PaymentMethod id, a test card name like `pm_card_visa`, or [the hosted checkout page](https://docs.fluveo.com/payments/checkout.md). See [Cards](https://docs.fluveo.com/payments/cards.md).

`application_fee_amount`, `transfer_data` and `on_behalf_of` are managed by Fluveo and are not part of the public PaymentIntent or Charge objects.

## Before you start

- Get a test secret key (`sk_test_...`) from the [Fluveo Dashboard](https://dash.fluveo.com) and send it as `Authorization: Bearer sk_test_...`. A checkout platform uses the key the merchant pastes into it; it never uses a key of its own. See [Authentication](https://docs.fluveo.com/start/authentication.md).
- Send an `Idempotency-Key` header on every POST that creates or changes money, and reuse it when you retry that POST: Fluveo answers with the first result and never charges twice. See [Idempotency](https://docs.fluveo.com/start/idempotency.md).
- Set up a webhook endpoint so you learn about payments that finish later, refunds and disputes. Listen for `payment_intent.succeeded` to fulfil and `payment_intent.payment_failed` to release the order, and check each event's `Fluveo-Signature` header first. See [Webhooks](https://docs.fluveo.com/webhooks.md) and [signatures](https://docs.fluveo.com/webhooks/signatures.md).
- Call the API over plain HTTP: curl, `fetch`, `requests` or any HTTP client. Install no server SDK.
- Test values for every outcome are on [Testing](https://docs.fluveo.com/start/testing.md).

Only test mode is open today: a `sk_live_` key is refused with a 403.

> **For AI agents:**
>
> One API for every store. Amounts are integers in the smallest currency unit. currency is one your account accepts (GET /v1/account shows default_currency; any other is a 400 on currency); the methods table on /payments says which currency each method charges in. Call Fluveo over plain HTTP with Authorization: Bearer sk_test_...; install no server SDK and call no other payments host. Never send a header that acts for another account, routing fields (transfer_data, on_behalf_of, application_fee_amount, transfer_group), or raw card numbers. In tests, pay a card with payment_method=pm_card_visa. Treat every id (pi_, ch_, py_, re_, po_, and dispute ids) as an opaque string. Never fulfil an order before payment_intent.succeeded arrives by signed webhook or GET /v1/payment_intents/{id} shows status succeeded.

## Next

- [Accept a payment](https://docs.fluveo.com/payments/accept-a-payment.md)
- [Quickstart](https://docs.fluveo.com/start.md)
- [Integrate with an AI agent](https://docs.fluveo.com/agents/integrate.md)
- [The PaymentIntents reference](https://docs.fluveo.com/api/payment_intents.md) lists every parameter.