FlintflintDocs

Node SDK

Use @flintpay/node when your integration runs in Node.js or TypeScript and you want typed request/response shapes, retry behavior, and async pagination helpers.

Install#

Bash
npm install @flintpay/node

Use the SDK from your server, worker, or other trusted backend environment. Do not ship your Flint API key in browser or mobile client code.

If you need to set up a Flint account before you have a normal API key, use DeveloperService first:

TypeScript
import { DeveloperService } from "@flintpay/node";

const developer = new DeveloperService({
  baseUrl: "https://api.withflintpay.com",
});

The preferred first-run flow on DeveloperService is:

TypeScript
const challenge = await developer.startSetup({
  email: "owner@example.com",
  firstName: "Ada",
  lastName: "Lovelace",
});

const verified = await developer.verifySetupEmail({
  verificationToken: challenge.verificationToken,
  verificationCode: "482193",
});

const state = await developer.getSetupState();

Use advanceSetup() when Flint still needs more information or needs to create a provider onboarding session, then call createSetupApiKey() once Flint returns status: "ready_for_api_key".

After setup, sandbox-management routes can use a normal external API key. The main Flint client exposes those routes under flint.developer.

What The SDK Wraps#

The SDK is a typed client over Flint's public contract. It maps clean TypeScript methods onto the supported external API surface, but it is not intended to expose every internal proto-only field or transport detail.

Use the SDK when you want:

  • camelCase method params and response fields
  • typed money objects, enums, and dates
  • built-in async pagination
  • consistent retry and error handling

Use raw HTTP when you are integrating from another language, need exact wire-level control, or want to work directly with the documented JSON payloads.

Initialize the Client#

TypeScript
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. Use a flint_test_... key for sandbox traffic and a flint_live_... key for live traffic.

For ongoing sandbox automation after setup:

TypeScript
const sandboxes = await flint.developer.listSandboxes();

For disposable sandbox automation, call resetSandbox() to clear a sandbox in place while keeping the same sandboxId.

If you need per-key request visibility for sandbox or CI traffic, issue a key with the developer.logs.self.read scope and read logs through flint.developerLogs.

First Calls#

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

TypeScript
const order = await flint.orders.create({
  lineItems: [
    {
      name: "Premium Widget",
      quantity: 1,
      unitPriceMoney: { amount: 2500, currency: "USD" },
    },
  ],
});

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

The payment intent amount is derived from the current order balance, the same way it is in the HTTP API.

Pagination#

List methods return an async iterable:

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

The same pattern works for webhook events and API request logs:

TypeScript
for await (const event of flint.webhooks.listEvents({
  webhookEndpointId: "whep_123",
  status: "failed",
})) {
  console.log(event.webhookEventId, event.lastError);
}

for await (const log of flint.developerLogs.list({
  status: "client_error",
  pathQuery: "/v1/orders",
})) {
  console.log(log.requestId, log.statusCode, log.errorCode);
}

Inspect one webhook event and its delivery attempts with:

TypeScript
const event = await flint.webhooks.getEvent("whev_123");
const attempts = await flint.webhooks.listDeliveryAttempts(event.webhookEventId);

Errors#

SDK requests throw FlintError with Flint's public error metadata:

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

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

Retries apply automatically to GET requests and to write requests that are idempotency-backed in the public contract.

Next Steps#

Rate this doc