@flintpay/node

Official Node.js and TypeScript SDK for the Flint payments API.

Use it to create and manage:

• customers
• orders
• payment intents
• checkout sessions
• payment links
• invoices
• subscriptions
• webhooks
• settings, analytics, API keys, devices, merchants, and users

Install

pnpm add @flintpay/node

Node >=18 is required.

Authentication

Create an API key in the Flint dashboard, then use it from your server:

import { Flint } from "@flintpay/node";

const flint = new Flint({
  apiKey: process.env.FLINT_API_KEY!,
});

By default the SDK talks to https://api.withflintpay.com.

Quick Start

Create an order, then create a payment intent from that order:

import { Flint } from "@flintpay/node";

const flint = new Flint({
  apiKey: process.env.FLINT_API_KEY!,
});

const order = await flint.orders.create({
  lineItems: [
    {
      name: "Coffee",
      quantity: 1,
      unitPriceMoney: { amount: 500, currency: "USD" },
    },
    {
      name: "Blueberry Muffin",
      quantity: 1,
      unitPriceMoney: { amount: 425, currency: "USD" },
    },
  ],
  buyerNote: "Pickup order",
});

const paymentIntent = await flint.paymentIntents.create({
  orderId: order.orderId,
});

Common Flows

Create a Customer

const customer = await flint.customers.create({
  name: "Ada Lovelace",
  email: "[email protected]",
  phoneNumber: "+15551234567",
});

Create a Payment Link

const paymentLink = await flint.paymentLinks.create({
  name: "Spring Merch Drop",
  lineItems: [
    {
      key: "shirt",
      name: "Limited Tee",
      quantity: 1,
      amountMoney: { amount: 3500, currency: "USD" },
    },
  ],
});

Create a Checkout Session

const session = await flint.checkoutSessions.create({
  quickPay: {
    lineItems: [
      {
        name: "Event Ticket",
        quantity: 2,
        unitPriceMoney: { amount: 2500, currency: "USD" },
      },
    ],
  },
});

Create an Invoice

const invoice = await flint.invoices.create({
  quickPay: {
    lineItems: [
      {
        name: "Consulting",
        quantity: 1,
        unitPriceMoney: { amount: 25000, currency: "USD" },
      },
    ],
  },
  recipientEmail: "[email protected]",
  reference: "INV-2026-001",
});

const sent = await flint.invoices.send(invoice.invoiceId);

Manage Webhooks

const endpoint = await flint.webhooks.create({
  url: "https://example.com/flint/webhooks",
  subscribedEvents: ["payment_intent.succeeded"],
  description: "Production webhook endpoint",
  enabled: true,
});

const rotated = await flint.webhooks.rotateWebhookSecret(
  endpoint.webhookEndpointId
);

Pagination

List endpoints return a FlintList, which supports both page access and async iteration:

for await (const customer of flint.customers.list({ limit: 25 })) {
  console.log(customer.customerId, customer.email);
}

Errors

SDK requests throw FlintError with normalized error types and remediation metadata when available:

import { FlintError } from "@flintpay/node";

try {
  await flint.orders.get("ord_does_not_exist");
} catch (error) {
  if (error instanceof FlintError) {
    console.error(error.type, error.code, error.message);
  }
}

Configuration

const flint = new Flint({
  apiKey: process.env.FLINT_API_KEY!,
  baseUrl: "https://api.staging.withflintpay.com",
  timeoutMs: 10_000,
  maxRetries: 2,
});

Defaults:

• baseUrl: https://api.withflintpay.com
• timeoutMs: 30000
• maxRetries: 2

Supported Resources

• customers
• orders
• items
• coupons
• paymentLinks
• paymentIntents
• paymentMethods
• refunds
• checkoutSessions
• subscriptionPlans
• subscriptions
• settings
• analytics
• apiKeys
• devices
• invoices
• merchants
• users
• webhooks

Current Scope

This SDK covers Flint’s public API-key-authenticated commerce, checkout, invoice, subscription, analytics, account, and webhook surfaces.

Developer bootstrap is separate because it uses a different pre-API-key authentication flow.

Development

pnpm build
pnpm typecheck
pnpm test
pnpm test:contract