FloPay
API Reference@flopay/node

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)
ParameterTypeRequiredDescription
secretKeystringYesYour Stripe secret key (e.g. sk_test_...).
optionsFloPayNodeOptionsNoAdditional configuration.

FloPayNodeOptions:

NameTypeDescription
apiVersionstringAPI version override.
stripeSecretKeystringStripe 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>
ParameterTypeRequiredDescription
paramsCreateSessionParamsYesSee 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',
  items: [{ providerItemId: 'prod_abc', totalAmount: 49.99 }],
  account: { userId: 'user_1', email: 'user@example.com' },
  successUrl: '/success',
  cancelUrl: '/cancel',
});

retrieve

Retrieve a checkout session from Stripe by ID.

checkout.sessions.retrieve(id: string): Promise<CheckoutSession>
ParameterTypeRequiredDescription
idstringYesStripe 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>
ParameterTypeRequiredDescription
idstringYesStripe 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[]>
ParameterTypeRequiredDescription
idstringYesStripe 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>
ParameterTypeRequiredDescription
params.emailstringYesCustomer email.
params.namestringNoCustomer full name.
params.metadataRecord<string, string>NoArbitrary 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>
ParameterTypeRequiredDescription
idstringYesStripe 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>
ParameterTypeRequiredDescription
idstringYesStripe customer ID.
params.emailstringNoUpdated email.
params.namestringNoUpdated name.
params.metadataRecord<string, string>NoUpdated 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
ParameterTypeRequiredDescription
payloadstring | BufferYesRaw request body.
signaturestringYesValue of the stripe-signature header.
secretstringYesWebhook endpoint secret (e.g. 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['stripe-signature'],
  'whsec_...'
);
 
switch (event.type) {
  case 'payment_intent.succeeded':
    // Handle successful payment
    break;
  case 'payment_intent.payment_failed':
    // Handle failed payment
    break;
}

Previous

Hooks

Next

Basic Card Payment

On this page