Documentation

The mental model behind the Flint API: orders are the center, and payments, checkout, invoices, and subscriptions attach to them.

How test mode works on Flint, why test keys are sandbox-bound, and how to create and reset isolated sandboxes for development, CI, and QA.

How Flint authentication works: the Authorization header, live vs sandbox-bound test keys, and what authentication and authorization errors mean.

How Flint represents money: integer minor units, the amount and currency object, and when to use unit_price_money vs amount_money.

Install and use the official @flintpay/node package for typed Flint Pay integrations in Node.js and TypeScript.

Install the Flint CLI to create resources, forward webhooks to localhost, and script the public API from your terminal or CI.

Simulate successful payments, declines, and 3D Secure with test cards, then verify orders, webhooks, refunds, and renewals in your sandbox.

The test-to-production checklist: swap keys, register a live webhook endpoint, confirm readiness, and verify before real money moves.

The order is Flint's durable commerce record; checkout sessions, payment intents, invoices, and payment links are collection surfaces attached to it. What that buys your integration, and when to skip it.

Collect card payments in your own UI with Stripe Elements and Flint's order-owned payment flow, including 3D Secure.

Collect a ConfirmationToken in the browser, confirm through Flint, handle typed client actions, and safely continue manual confirmation.

Offer buyer-present Affirm payments with Flint, Stripe Elements, clean browser returns, and server-owned payment state.

Create a hosted or embedded Flint checkout for one buyer, then verify the result from your backend.

Create an active flat-rate shipping method, quote it for a buyer, and record the selected option.

Create a reusable hosted checkout URL you can share anywhere. Sell products, collect donations, ticket events, and start subscriptions with no frontend code.

Add durable, responsive images to products, variants, bundles, subscription plans, payment links, and merchant branding.

Three hosted ways to collect payment, one orders-first engine underneath. Decide in two questions, see the boundaries, and learn how to combine them.

Place a hold on a card with delayed capture, then capture in full or in part, or cancel to release the hold.

Accept one-time US bank payments through hosted checkout or a standalone PaymentIntent, then handle delayed settlement, returns, and refunds safely.

How order payments recover from declines, 3D Secure, finalizing, and lost responses. Read the payment attempt, branch on is_resumable, and retry without losing the order.

Issue full, partial, and line-item refunds, track them through their asynchronous lifecycle, and handle the ones that fail.

Let buyers add a tip and add your own fees, like delivery and service charges, to an order. Fixed and percent amounts, tax treatment, and how both land in order totals.

Calculate US sales tax on orders, supply a tax location, read jurisdiction breakdowns, and control how tax reverses on a refund.

Build automatic discounts, code campaigns, buy-X-get-Y offers, and stacking rules with Flint promotions.

Evaluate every payment attempt, author deterministic rules and lists, resolve reviews, and respond to fraud warnings.

How Flint's two merchant-owned surfaces fit together: an embedded checkout for the purchase, a customer session for the account, and the seam between them.

Build a merchant-owned checkout on your own domain with an embedded checkout session, Stripe Elements, and a backend-for-frontend, while Flint stays authoritative for the order and the payment.

The trust boundary for a merchant-owned checkout: what your backend holds, what the browser may see, which controls are yours, and how card data actually flows for PCI scoping.

Build a customer account on your own front end with /v1/me, where the credential decides whose data comes back and Flint enforces ownership for you.

Take merchandise back and settle what the buyer is owed. The Return model, the statuses that answer each question, and which integration to build.

Take one item back and refund it in sandbox, from discovering what is returnable to watching the refund settle.

Let buyers start a return themselves: show what is eligible, compare outcomes, print a label, and track the parcel back.

Take merchandise back at a register in one call, with a single scope and a key you can safely replay.

Record what physically arrived, what condition it was in, and where it ended up, from a system that has no authority to refund.

Refunds, exchanges, and replacements: what the buyer gets, what it costs them, when it moves, and how to fix it afterwards.

Write the rules once: windows, who pays return shipping, restocking fees, and what decides itself. Plus the four reason vocabularies and which is which.

Stock a location, sell a tracked variant, and follow one unit from receipt through a paid, fulfilled order.

Bill a specific customer for a specific amount. Flint emails a hosted payment page, tracks the balance through card, check, and wire payments, and renders the PDF.

Model recurring pricing with plans, sign customers up through hosted checkout or your own UI, and run the full lifecycle. Trials, renewals as orders, failed-payment recovery, pause, and cancel.

Give buyers a place to track orders, manage subscriptions, and start returns. Use Flint's account under your brand and domain, or build your own against the API.

Mint a buyer-scoped credential after your own login, refresh it with rotating tokens, and revoke it on sign-out or account takeover.

Turn off Flint's buyer email one family at a time and send your own from the webhook events that keep firing.

Receive signed event notifications when payments, orders, and subscriptions change, verify Standard Webhooks signatures, and process each one exactly once.

Every webhook event Flint can send: what triggers it, what its data payload carries, and which event to build each job on.

Pick the right Flint webhook event level for reconciliation, fulfillment, dunning, entitlements, saved payment methods, and platform readiness.

Retry any write safely with idempotency keys. How replays, conflicts, key scoping, and the 24-hour replay window work on the Flint API.

Page through any list endpoint with page_size, page_token, and next_page_token. One cursor pattern for every resource, plus sorting, filtering, and how to know when you are done.

Read the Flint error envelope, branch on types and codes, retry safely with idempotency keys, and handle declines as outcomes rather than errors.

How Flint Pay rate limits work: per-key and per-merchant budgets, the anatomy of a 429, safe retry patterns, and how to design an integration that stays under the limits.

Turn a request_id into a diagnosis with request logs and resource timelines that stitch API calls and webhook deliveries together.

How to handle Flint secrets in production: server-side-only keys, source-control hygiene, least-privilege scopes, expiry and rotation, and what to do the moment a key leaks.

Tie every settled dollar back to an order and match a bank deposit to the balance transactions that funded it.

What Flint charges to process a payment, when the fee becomes final, and how to read your net on every payment and balance transaction.

Generate versioned CSV reports of orders, payments, Flint billing, balance activity, payouts, and tax, then download the completed file with your API key.

What you owe Flint and any account credit you hold. The fees and subscription charges that build it, how credit is applied, how Flint collects from your balance, and how to reconcile every entry.

Read an order's human-readable history log to render a timeline and debug what happened, without treating it as a source of truth.

Respond to disputes and chargebacks operationally: monitor via events, meet evidence deadlines, and reconcile the money impact.

Every status value across orders, payments, refunds, invoices, subscriptions, fulfillment, and returns, which ones are final, and how to read them without guessing.

Migrate common Stripe integrations to Flint for subscriptions, one-time payments, payment links, invoices, saved cards, refunds, and webhooks.

Migrate common Square payment flows to Flint for hosted checkout, embedded card payments, cards on file, subscriptions, invoices, refunds, and webhooks.

Give AI coding agents one URL with Flint Pay schemas, docs, and integration conventions.

Connect an AI coding agent to the Flint docs over the Model Context Protocol for live search and API reference lookups.

Provision a Flint merchant, issue the first sandbox key, and hand provider-owned verification to the account owner in an embedded browser flow.

Build an installable Flint partner app, send merchants through hosted OAuth install, exchange install tokens, and subscribe to lifecycle webhooks.