Payments

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#

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:

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#

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 for when money becomes available and which bank account receives it.

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

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

import requests

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

<?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. See Cards.

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 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.
• 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.
• 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 and signatures.
• 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.

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

Next#

• Accept a payment
• Quickstart
• Integrate with an AI agent
• The PaymentIntents reference lists every parameter.