FloPayGetting started
Terminology
Shared Flo terms for clients, integrations, billing objects, and webhook delivery.
Terminology
Flo uses a small set of consistent terms across the REST API, SDKs, dashboard experiences, and webhook payloads. This page defines the core language used throughout the platform.
Core Terms
| Term | Meaning |
|---|---|
| Client | A business, brand, platform, or merchant that uses Flo to orchestrate payments. A client owns checkout sessions, webhook endpoints, and the relationship with its end users. |
| User | The client's end customer: the person making a payment, starting a subscription, or receiving service after purchase. In Flo webhooks, user.id is the Flo user identifier and user.clientUserId is the client's own identifier when one was supplied. |
| Gateway | The payment system Flo uses to execute billing activity. This can be a payment provider or payment orchestrator such as Stripe, Worldpay, or Adyen. Flo aims to keep the client-facing contract gateway-agnostic wherever possible. |
Billing Objects
| Term | Meaning |
|---|---|
| Checkout Session | A short-lived checkout context created through the SDK or REST API. It groups together the user, pricing, items, subscriptions, redirect URLs, and the information needed to complete a payment flow. In practice, it is the closest Flo concept to a cart or checkout attempt. |
| Item | A one-off product, entitlement, or purchase line sold through Flo. Items are non-recurring and typically represent a single purchase rather than an ongoing billing relationship. |
| Subscription | A recurring billing relationship managed through Flo. A subscription can renew, pause, resume, cancel, expire, and generate invoices over time. |
| Invoice | A billing record representing an amount due, billed, paid, overdue, voided, updated, or deleted. Invoices are used for both recurring billing flows and broader transaction reporting. |
| Transaction | The billing outcome record associated with a checkout or invoice. A transaction can succeed, fail, be refunded, or require follow-up. Flo uses transaction as the canonical term and keeps it separate from gateway-specific terminology where possible. |
Delivery And Integration Terms
| Term | Meaning |
|---|---|
| REST API | Flo's server-side API surface. Use it when you want to create sessions, configure webhooks, inspect delivery history, or integrate from non-JavaScript environments. |
| FloPay SDK | The JavaScript, React, Node, and shared packages that simplify frontend and backend integration with Flo. The SDK is one integration surface, not the whole platform. |
| Playground | Flo's hosted demo environment for exploring checkout flows and understanding how the platform behaves before integrating it into your own systems. |
| Webhook | An outbound HTTP event sent by Flo to a client-controlled endpoint. Flo webhooks use Flo event names and Flo object shapes, even when the underlying billing activity originated from a specific gateway. |
| Client Webhook Endpoint | A webhook destination configured by a client to receive Flo events. Each endpoint can subscribe to specific event types and receives signed deliveries from Flo. |
Helpful Notes
- Flo terminology is intentionally client-facing. Where possible, integrate against Flo terms like
subscription,invoice,transaction,user, and Flo event types rather than gateway-native names. - In webhook payloads, top-level
eventIdis Flo's delivery identifier for that endpoint, not the upstream gateway event id. - Gateway identifiers and gateway event types can still appear in trace fields for debugging, but they should not be the primary contract your application depends on.
- If a term appears ambiguous in a payload or endpoint, prefer the Flo definition on this page over assumptions from a specific gateway.