> 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.

# Quickstart

Create your first payment with the Fluveo `/v1` API in a few minutes. You'll
authenticate with a secret key, create a PaymentIntent, retrieve it, and learn
where the flow goes next.

The curated `/v1` contract uses Stripe-shaped secret-key auth, form bodies, and
objects. Only operations in the generated API Reference carry that promise.

## Before you start

You need a **sandbox secret key** (`sk_test_...`). Getting one takes three steps
in the dashboard:

1. **Sign up** for a Fluveo account.
2. **Create a merchant** — pick your region (this fixes your settlement
   currency). Fluveo provisions the merchant and shows your first secret key.
3. **Copy the secret key.** It is shown **exactly once**, right after the
   merchant is created (and again whenever you create a key on the API-keys
   page). Store it now — Fluveo only keeps a hash and can never re-display it.
   If you lose it, create a new key and revoke the old one.

Onboarding issues `sk_test_*` plus a browser-side `pk_test_*`. Use the secret
key with `https://api.devfluveo.com`; the key selects test mode. Public live `/v1`
admission is not enabled. Secret keys are **server-side credentials** —
keep them out of browser code and version control (see [authentication](/authentication)).

## Step 1 — Create a PaymentIntent

A PaymentIntent (see the [API Reference](/api-reference)) tracks a payment from
creation through authorization and capture. Create one with an `amount` (in the
smallest currency unit — `4242` is \$42.42) and a `currency`:

```bash
curl https://api.devfluveo.com/v1/payment_intents \
  -u sk_test_...: \
  -d amount=4242 \
  -d currency=usd
```

The `-u sk_test_...:` flag is HTTP Basic Auth with your secret key as the
username and an empty password (note the trailing colon). The response is a
PaymentIntent in the `requires_payment_method` state:

```json
{
  "id":            "pi_1A9e8AzB2xQRH9JfQu5N",
  "object":        "payment_intent",
  "status":        "requires_payment_method",
  "amount":        4242,
  "currency":      "usd",
  "client_secret": "pi_1A9e8AzB2xQRH9JfQu5N_secret_xT…",
  "created":       1769349712,
  "capture_method": "automatic",
  "livemode":      false
}
```

Hold on to two fields:

* **`id`** (`pi_...`) — use it to retrieve, confirm, capture, or cancel the payment.
* **`client_secret`** — sensitive flow state. Never log it or expose it before a
  browser authentication product is explicitly promoted; publishable keys are
  not issued today.

## Step 2 — Retrieve it

Fetch the PaymentIntent back by `id` to confirm it exists and check its status:

```bash
curl https://api.devfluveo.com/v1/payment_intents/pi_1A9e8AzB2xQRH9JfQu5N \
  -u sk_test_...:
```

## Step 3 — Confirm and capture

Confirmation moves the payment toward `succeeded`. In test mode, confirm with one
of Stripe's documented test PaymentMethods:

```bash
curl https://api.devfluveo.com/v1/payment_intents/pi_1A9e8AzB2xQRH9JfQu5N/confirm \
  -u sk_test_...: \
  -d payment_method=pm_card_visa
```

In production the card is collected in the browser with
[VGS Collect](/overview#external-card-vault-vgs-outbound-proxy) and you pass a vault alias,
never a raw PAN, so card numbers never touch your servers.

With the default `capture_method=automatic`, a confirmed payment captures
immediately. Set `capture_method=manual` at creation to authorize now and capture
later. See the full [API Reference](/api-reference) for the complete lifecycle,
every field, and the error table.

## Safe retries

Supported writes accept `Idempotency-Key`. Current replay semantics are not a
24-hour byte-identical Stripe replay; review the documented divergence before
building retry policy:

```bash
curl https://api.devfluveo.com/v1/payment_intents \
  -u sk_test_...: \
  -H "Idempotency-Key: $(uuidgen)" \
  -d amount=4242 \
  -d currency=usd
```

## Next steps

* **[Authentication](/authentication)** — Basic vs. Bearer and key safety.
* **[Errors](/errors)** — the error envelope and how to handle each type.
* **[Webhooks](/webhooks)** — current quarantine and verifier boundary.
* **[API Reference](/api-reference)** — every contracted test-mode operation.