Examples

This repository contains runnable Flovia SDK examples as a standalone Bun workspace. It intentionally does not vendor the SDK source; install @flovialabs/sdk from the package registry or replace the dependency with your local SDK package while developing.

Note: @flovialabs/sdk is published to a private registry. You need access credentials configured (e.g. in .npmrc) to install it. Contact the Flovia team if you need access.

The examples intentionally use different levels of detail. Choose the smallest one that matches what you are trying to copy.

Runnable demos

Use these when you need framework/runtime-specific integration details:

Framework/runtime demos

• demos/hono/ - Hono middleware setup in a runnable Bun server.
• demos/express/ - Express middleware setup in a runnable Node server.
• demos/manual-tracking/ - Manual request and payment tracking as a runnable script.
• demos/mpp-native-hono/ - Hono setup with native MPP middleware.
• demos/nextjs/ - Next.js App Router route handler with manual tracking.
• demos/cloudflare-workers/ - Cloudflare Workers flushing with ctx.waitUntil.

Reference example

Use this when you want to see a small end-to-end paid data API:

• reference/practical-data-api/ - Hono app with paid route, payment response handling, webhook settlement tracking, and metadata allowlisting.

Keep customer-facing configuration minimal. Advanced controls such as endpoint patterns, protocol declarations, wallet hashing knobs, and sampling should stay out of examples unless the example is specifically about that behavior.

Required Flovia configuration

To run this project's code, you need the following Flovia configuration values:

• FLOVIA_API_KEY
• FLOVIA_PROVIDER_ID
• FLOVIA_PROVIDER_SECRET

Config value	Description
apiKey	Used to authenticate with the Ingest API. Do not put it in the request body or query string.
providerId	Merchant/provider identifier in the SDK config. Tenancy authority comes from the API key.
providerSecret	Secret used to HMAC values such as flowId and joinHint. Separate from apiKey.