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

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

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

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:

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 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 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.devfluveo.com/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.