FloPayFloPay (Node)
Server-side FloPay SDK for checkout session management, customer operations, and webhook handling.
FloPay
Server-side FloPay SDK. Supports checkout session creation via the billing API, direct Stripe operations for customers, and webhook event construction.
import { FloPay } from '@flopay/node';Constructor
new FloPay(secretKey: string, options?: FloPayNodeOptions)| Parameter | Type | Required | Description |
|---|---|---|---|
secretKey | string | Yes | Your Stripe secret key (e.g. sk_test_...). |
options | FloPayNodeOptions | No | Additional configuration. |
FloPayNodeOptions:
| Name | Type | Description |
|---|---|---|
apiVersion | string | API version override. |
stripeSecretKey | string | Stripe secret key (when using Stripe-specific operations). |
Throws: FloPayError with type 'authentication_error' if secretKey is empty.
const flopay = new FloPay('sk_test_...');checkout.sessions
create
Create a checkout session via the billing API. Posts to {billingApiUrl}/v1/checkouts/sessions.
checkout.sessions.create(params: CreateSessionParams): Promise<CheckoutSessionResult>| Parameter | Type | Required | Description |
|---|---|---|---|
params | CreateSessionParams | Yes | See CreateSessionParams. |
Returns: Promise<CheckoutSessionResult>
{ status: 201, redirectUrl: string }-- session created, redirect URL available.{ status: 204 }-- payment method already on file.{ status: number }-- other status.
const result = await flopay.checkout.sessions.create({
billingApiUrl: 'https://billing.example.com',
checkoutBaseUrl: 'https://checkout.example.com',
clientId: 'client_123',
currency: 'USD',
products: [{ code: 'pro_plan', totalAmount: 49.99 }],
account: { userId: 'user_1', email: 'user@example.com' },
successUrl: '/success',
cancelUrl: '/cancel',
});Session-level currency is required. The SDK throws FloPayError({ type: 'validation_error', code: 'CurrencyRequired' }) synchronously — before the HTTP request — when neither the session-level currency nor any per-line currency resolves. Pass currency at the top of the session for the cleanest behavior.
The create response carries a nonce that authenticates every subsequent /v1/checkouts/* call as the x-checkout-session-token header. Forward it to your client (or your server-side continuation calls) and echo it on each request. See the Checkout session token guide.
retrieve
Retrieve a checkout session from Stripe by ID.
checkout.sessions.retrieve(id: string): Promise<CheckoutSession>| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stripe checkout session ID. |
Returns: Promise<CheckoutSession> -- normalized session object.
const session = await flopay.checkout.sessions.retrieve('cs_test_xxx');
console.log(session.status); // 'open' | 'complete' | 'expired'expire
Expire an open checkout session on Stripe.
checkout.sessions.expire(id: string): Promise<CheckoutSession>| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stripe checkout session ID. |
Returns: Promise<CheckoutSession> -- the expired session.
listLineItems
List line items for a Stripe checkout session.
checkout.sessions.listLineItems(id: string): Promise<LineItem[]>| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stripe checkout session ID. |
Returns: Promise<LineItem[]> -- array of line items with price and quantity.
const items = await flopay.checkout.sessions.listLineItems('cs_test_xxx');
// [{ price: 'price_xxx', quantity: 1 }]customers
create
Create a customer on Stripe.
customers.create(params: CreateCustomerParams): Promise<Customer>| Parameter | Type | Required | Description |
|---|---|---|---|
params.email | string | Yes | Customer email. |
params.name | string | No | Customer full name. |
params.metadata | Record<string, string> | No | Arbitrary metadata. |
Returns: Promise<Customer>
const customer = await flopay.customers.create({
email: 'user@example.com',
name: 'Jane Doe',
});retrieve
Retrieve a customer from Stripe by ID.
customers.retrieve(id: string): Promise<Customer>| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stripe customer ID. |
Returns: Promise<Customer>
Throws: FloPayError with type 'api_error' and code 'resource_missing' if the customer has been deleted.
update
Update a customer on Stripe.
customers.update(id: string, params: UpdateCustomerParams): Promise<Customer>| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stripe customer ID. |
params.email | string | No | Updated email. |
params.name | string | No | Updated name. |
params.metadata | Record<string, string> | No | Updated metadata. |
Returns: Promise<Customer>
const updated = await flopay.customers.update('cus_xxx', {
name: 'Jane Smith',
});webhooks
constructEvent
Construct and verify a webhook event from a raw payload and signature.
webhooks.constructEvent(
payload: string | Buffer,
signature: string,
secret: string
): WebhookEvent| Parameter | Type | Required | Description |
|---|---|---|---|
payload | string | Buffer | Yes | Raw request body. |
signature | string | Yes | Value of the Flo-Signature header. |
secret | string | Yes | Webhook endpoint secret (e.g. flo_whsec_...). |
Returns: WebhookEvent -- verified event with id, type, data, and created.
Throws: If the signature verification fails.
import { FloPay } from '@flopay/node';
const flopay = new FloPay('sk_test_...');
// In your webhook handler:
const event = flopay.webhooks.constructEvent(
req.body,
req.headers['flo-signature'],
'flo_whsec_...'
);
switch (event.type) {
case 'payment_intent.succeeded':
// Handle successful payment
break;
case 'payment_intent.payment_failed':
// Handle failed payment
break;
}