FloPay (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',
});

Pass captureMethod: 'manual' to create an eligible item-only card authorisation. Omitting it preserves immediate capture, which remains the default. An authorised checkout reports status: 'authorized' with paymentId and authorizationExpiresAt through the checkout result.

Capture is not an SDK method. Call PUT /v1/payments/{paymentId}/capture from a trusted server with merchant authentication and a stable Idempotency-Key; see the payments REST reference.

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 direct Stripe webhook event from a raw payload and Stripe signature. This method does not verify Flo's normalized outbound merchant webhooks or their Flo-Signature header; use the Flo webhook delivery contract for those events.

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 Stripe's `Stripe-Signature` header.
`secret`	`string`	Yes	Stripe webhook endpoint secret (for example `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 a direct Stripe webhook handler:
export async function POST(request: Request) {
  const payload = await request.text();
  const stripeSignature = request.headers.get('stripe-signature');
  if (!stripeSignature) {
    return new Response('Missing Stripe signature', { status: 400 });
  }

  let event;
  try {
    event = flopay.webhooks.constructEvent(
      payload,
      stripeSignature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (error) {
    if (
      error instanceof Error &&
      'type' in error &&
      error.type === 'StripeSignatureVerificationError'
    ) {
      return new Response('Invalid Stripe signature', { status: 400 });
    }
    throw error;
  }

  console.log(event.type);
  return new Response(null, { status: 204 });
}

On this page