@flopay/node

Server-side FloPay SDK for Node.js. Creates checkout sessions via the billing API, manages Stripe customers, and verifies webhooks.

Installation

pnpm add @flopay/node

Depends on stripe (^22.2.0) and @flopay/shared.

Quick Start

Initialize

import { FloPay } from '@flopay/node';

const flopay = new FloPay('sk_test_...');
// Direct Stripe operations default to API version 2026-04-22.dahlia.

Create a Checkout Session (Billing API)

const result = await flopay.checkout.sessions.create({
  billingApiUrl: 'https://billing.example.com',
  checkoutBaseUrl: 'https://checkout.example.com',
  clientId: 'client_123',
  items: [{
    providerItemId: 'prod_abc',
    providerItemName: 'Pro Plan',
    totalAmount: 49.99,
    overrideAmount: 24.99,
    currency: 'USD',
  }],
  subscriptions: [{
    providerPlanId: 'plan_xyz',
    providerPlanName: 'Monthly Plan',
    totalAmount: 9.99,
    currency: 'USD',
  }],
  account: {
    userId: 'user_1',
    email: '[email protected]',
    firstName: 'John',
    lastName: 'Doe',
  },
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
  checkoutMode: 'confirm',   // 'confirm' | 'auto' | 'full'
  couponCodes: ['SAVE10'],
  tagsData: { googleContainerId: 'GTM-XXXX' },
  redirectParams: { email: '[email protected]', mode: 'confirm' },
  timeoutMs: 12000,
});

// result = { status: 201, redirectUrl: 'https://checkout.example.com/secure?id=uuid&...' }
// result = { status: 204 }  (payment method already on file)

To authorise an eligible one-time card cart without capturing it, pass captureMethod: 'manual' to checkout.sessions.create. Do not combine manual capture with subscriptions; the SDK rejects that cart before making a request. Omitting the option preserves immediate capture and leaves the wire key absent.

The later full capture is intentionally not an @flopay/node method. Use the merchant-authenticated REST endpoint from trusted server code with a stable Idempotency-Key; never expose merchant credentials to a browser. See the repository's pre-authorisation guide.

Saved-card management is also intentionally not an @flopay/node credential surface. From trusted merchant server code, use the authenticated REST API to list display-only methods, create a setup session, and delete an eligible method; pass only the resulting setup sessionId and nonce to <FloPayCardSetup> in @flopay/react. Replacement is setup-first, then delete, so a failed or cancelled setup leaves the existing card intact. The coordinated integration guide is tracked in TeamFloPay/docs#38.

Retrieve / Expire a Checkout Session (Stripe Direct)

const session = await flopay.checkout.sessions.retrieve('cs_test_...');
// { id, clientSecret, mode, status, amount, currency, metadata }

const expired = await flopay.checkout.sessions.expire('cs_test_...');

const lineItems = await flopay.checkout.sessions.listLineItems('cs_test_...');
// [{ price: 'price_xxx', quantity: 1 }]

Manage Customers

const customer = await flopay.customers.create({
  email: '[email protected]',
  name: 'John Doe',
  metadata: { plan: 'pro' },
});
// { id: 'cus_xxx', email: '...', firstName: 'John', lastName: 'Doe' }

const retrieved = await flopay.customers.retrieve('cus_xxx');

const updated = await flopay.customers.update('cus_xxx', {
  name: 'Jane Doe',
  metadata: { plan: 'enterprise' },
});

Verify Webhooks

import { FloPay } from '@flopay/node';

const flopay = new FloPay('sk_test_...');

// In your webhook handler (e.g. Express, Next.js API route):
const event = flopay.webhooks.constructEvent(
  requestBody,        // raw body string or Buffer
  signatureHeader,    // Stripe-Signature header
  'whsec_...',        // webhook signing secret
);

console.log(event.type);     // e.g. 'checkout.session.completed'
console.log(event.data);     // event payload
console.log(event.created);  // unix timestamp

API Reference

Constructor

new FloPay(secretKey: string, options?: FloPayNodeOptions)

| Parameter | Type | Description | |-----------|------|-------------| | secretKey | string | Stripe secret key (sk_test_... or sk_live_...). Required. | | options.apiVersion | string? | Direct Stripe API version override. Defaults to 2026-04-22.dahlia. | | options.stripeSecretKey | string? | Explicit Stripe key override for direct Stripe operations. |

flopay.checkout.sessions

| Method | Returns | Description | |--------|---------|-------------| | create(params) | Promise<CheckoutSessionResult> | Creates a session via billing API (POST /v1/checkouts/sessions). Returns { status: 201, redirectUrl, nonce } or { status: 204 }. The nonce is the session-bound checkout token returned by the backend; forward it as x-checkout-session-token on every continuation call against the same session. | | retrieve(id) | Promise<CheckoutSession> | Retrieves a Stripe checkout session and normalizes it | | expire(id) | Promise<CheckoutSession> | Expires a Stripe checkout session | | listLineItems(id) | Promise<LineItem[]> | Lists line items for a Stripe checkout session |

flopay.customers

| Method | Returns | Description | |--------|---------|-------------| | create(params) | Promise<Customer> | Creates a Stripe customer | | retrieve(id) | Promise<Customer> | Retrieves a Stripe customer. Throws if deleted. | | update(id, params) | Promise<Customer> | Updates a Stripe customer |

flopay.webhooks

| Method | Returns | Description | |--------|---------|-------------| | constructEvent(payload, signature, secret) | WebhookEvent | Verifies and parses a Stripe webhook event |

Types

| Type | Description | |------|-------------| | FloPayNodeOptions | Constructor options | | CreateSessionParams | Full session creation parameters (from @flopay/shared), including optional captureMethod: 'automatic' \| 'manual' | | CheckoutSessionResult | { status: 201, redirectUrl, nonce } / { status: 204 } / { status: number } | | CheckoutSession | Normalized session; status can be authorized, with paymentId and authorizationExpiresAt, for manual capture | | Customer | id, email, firstName?, lastName? | | WebhookEvent | id, type, data, created |