Guides

Migrate from Stripe

Move only the operations in Fluveo's curated contract.

Fluveo’s /v1 API matches only the operations and fields in the generated API Reference. A method or field in a Stripe SDK does not mean Fluveo supports it.

The long-form source list is docs/api/stripe-divergences.md.

Read this before changing the base URL

Stripe assumptionFluveo behaviorAction
Test and live secret keysOnboarding issues only sk_test_*; live mode is not open.Use a Fluveo sk_test_* key.
pk_* and rk_* keysFluveo issues neither publishable nor restricted keys.Keep secret keys on your server. Do not send pk_* or rk_*.
JSON request bodiesContracted Stripe-shaped writes use form encoding.Send application/x-www-form-urlencoded.
Unknown list filters may be ignoredUnknown or unsupported list filters return named 400 errors.Send only filters shown in the API Reference.
A saved pm_* can be attached to a PaymentIntentpayment_method: "pm_..." returns a named 400.Use the contracted inline card path through the approved vault boundary.
Stripe webhook endpoint secret rotationWebhookEndpoint management is contracted-test; rotate_secret is a Fluveo extension.Use rotation only when replacing the endpoint secret.
Subscriptions can be canceledWave 1 contracts create, list, and retrieve only. There is no cancel or automatic renewal.Keep cancellation outside the Fluveo API until cancel is added.
SetupIntents are readyAll six SetupIntent operations are contracted in test mode, but list returns a named 400 until tenant-scoped storage exists.Use the point operations. Do not infer a merchant list from shared processor rows.
Every Stripe response field existsFluveo returns only fields declared for the contracted operation.Check that a field exists before reading it.

Use an official Stripe SDK only for the contracted subset

The official Stripe models describe more fields and methods than Fluveo returns. Strict clients such as stripe-java and async-stripe can fail while reading a valid Fluveo response when they require a field outside Fluveo’s subset. JavaScript stripe-node and dynamic stripe-python use are supported for contracted operations, but your code must still check optional or absent fields.

Configure official stripe-node with its supported host, protocol, and port options:

1import Stripe from "stripe";
2
3const stripe = new Stripe(process.env.FLUVEO_API_KEY!, {
4  host: "api.fluveo.dev",
5  protocol: "https",
6  port: 443,
7});

Configure current stripe-python with base_addresses:

1import os
2from stripe import StripeClient
3
4stripe = StripeClient(
5    os.environ["FLUVEO_API_KEY"],
6    base_addresses={"api": "https://api.fluveo.dev"},
7)

Use only methods present in the generated API Reference. SDK method presence is not a capability check.

Direct HTTP example

$curl https://api.fluveo.dev/v1/payment_intents \
>  -u sk_test_example: \
>  -H 'Content-Type: application/x-www-form-urlencoded' \
>  -d amount=4242 \
>  -d currency=usd

Basic authentication (key as username, empty password) and Bearer authentication are supported for contracted operations. Do not send a processor api-key, processor merchant/profile id, Stripe-Account, publishable key, or restricted key.

Webhook differences from Stripe

Fluveo’s local SDK helpers can verify test signatures. They do not register a merchant webhook or prove public delivery. Keep Stripe webhooks in place and poll Fluveo’s contracted single-object and list GET operations until Events and WebhookEndpoints become merchant-public.

Next