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.

The MVP issues only sk_test_*. Use https://api.fluveo.dev; the key selects test mode. sk_live_* and publishable keys are not issued. Secret keys are server-side credentials — keep them out of browser code and version control (see authentication).

Step 1 — Create a PaymentIntent

A PaymentIntent (see the 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:

$
curl https://api.fluveo.dev/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:

1
{
2
  "id":            "pi_1A9e8AzB2xQRH9JfQu5N",
3
  "object":        "payment_intent",
4
  "status":        "requires_payment_method",
5
  "amount":        4242,
6
  "currency":      "usd",
7
  "client_secret": "pi_1A9e8AzB2xQRH9JfQu5N_secret_xT…",
8
  "created":       1769349712,
9
  "capture_method": "automatic",
10
  "livemode":      false
11
}

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:

$
curl https://api.fluveo.dev/v1/payment_intents/pi_1A9e8AzB2xQRH9JfQu5N \
>
  -u sk_test_...:

Step 3 — Confirm and capture

Confirmation moves the payment toward succeeded. Card details are collected outside Fluveo with VGS Collect so a raw PAN never touches your servers or ours — you confirm with VGS aliases (for example tok_sandbox_xxxx), not real card numbers, which Fluveo rejects:

$
curl https://api.fluveo.dev/v1/payment_intents/pi_1A9e8AzB2xQRH9JfQu5N/confirm \
>
  -u sk_test_...: \
>
  --data-urlencode 'payment_method_data[card][card_number]=tok_sandbox_xxxx' \
>
  --data-urlencode 'payment_method_data[card][card_cvc]=<vgs_cvc_alias>'

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

$
curl https://api.fluveo.dev/v1/payment_intents \
>
  -u sk_test_...: \
>
  -H "Idempotency-Key: $(uuidgen)" \
>
  -d amount=4242 \
>
  -d currency=usd

Next steps

• Authentication — Basic vs. Bearer and key safety.
• Errors — the error envelope and how to handle each type.
• Webhooks — current quarantine and verifier boundary.
• API Reference — every contracted test-mode operation.