# Flint Pay developer documentation

> Flint is a commerce-first payments API: orders, payments, subscriptions,
> invoices, and webhooks on one surface. Requests are plain HTTP+JSON
> authenticated with an API key. Append .md to any docs URL for raw Markdown.

## Start here

- [Agent skill file](https://developers.withflintpay.com/SKILL.md): condensed, machine-oriented integration instructions — read this first if you are an AI agent
- [OpenAPI spec](https://api.withflintpay.com/v1/openapi.json): the complete public HTTP surface

## Guides

- [Accept your first payment](https://developers.withflintpay.com/docs/guides/accept-first-payment.md): Take a $25 test card payment through Flint-hosted checkout with curl, then confirm from the API that the order is paid.
- [ACH debit payments](https://developers.withflintpay.com/docs/guides/ach-debit.md): Accept one-time US bank payments through hosted checkout or a standalone PaymentIntent, then handle delayed settlement, returns, and refunds safely.
- [Add shipping to a checkout](https://developers.withflintpay.com/docs/guides/add-shipping-to-checkout.md): Set up flat-rate shipping once, then let hosted checkout collect the address and shipping choice.
- [Affirm payments](https://developers.withflintpay.com/docs/guides/affirm.md): Offer buyer-present Affirm payments with Flint, Stripe Elements, clean browser returns, and server-owned payment state.
- [API & agent onboarding](https://developers.withflintpay.com/docs/guides/api-agent-onboarding.md): Provision a Flint merchant, issue the first sandbox key, and hand provider-owned verification to the account owner in an embedded browser flow.
- [Key security](https://developers.withflintpay.com/docs/guides/api-key-security.md): 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.
- [API versions and upgrades](https://developers.withflintpay.com/docs/guides/api-versions-and-upgrades.md): Pin your Flint API version, read the served version on every response, test an upgrade with the Flint-Version header, roll back within 72 hours, and upgrade webhook endpoints and partner apps on their own schedule.
- [Authentication](https://developers.withflintpay.com/docs/guides/authentication.md): How to send your Flint API key, how test and live keys select a mode and sandbox, how to manage keys over the API, and what each authentication error means.
- [Checkout sessions](https://developers.withflintpay.com/docs/guides/checkout-sessions.md): Create a hosted or embedded Flint checkout for one buyer, then verify the result from your backend.
- [CLI](https://developers.withflintpay.com/docs/guides/cli.md): Install the Flint CLI to create resources, forward webhooks to localhost, and script the public API from your terminal or CI.
- [Credit notes](https://developers.withflintpay.com/docs/guides/credit-notes.md): Correct an issued invoice without moving money. Credit specific lines, allocate the credit against the balance, and hand the customer a numbered document.
- [Customer accounts](https://developers.withflintpay.com/docs/guides/customer-accounts.md): 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.
- [Customer email delivery](https://developers.withflintpay.com/docs/guides/customer-email-delivery.md): Turn off Flint's buyer email one family at a time and send your own from the webhook events that keep firing.
- [Customer sessions](https://developers.withflintpay.com/docs/guides/customer-sessions.md): Mint a buyer-scoped credential after your own login, refresh it with rotating tokens, and revoke it on sign-out or account takeover.
- [Debugging](https://developers.withflintpay.com/docs/guides/debugging-requests.md): Turn a request_id into a diagnosis with request logs and resource timelines that stitch API calls and webhook deliveries together.
- [Handling declines & payment attempts](https://developers.withflintpay.com/docs/guides/declines-and-payment-attempts.md): 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.
- [Embedded payments with Stripe Elements](https://developers.withflintpay.com/docs/guides/embedded-payments.md): Collect card payments in your own UI with Stripe Elements and Flint's order-owned payment flow, including 3D Secure.
- [Error handling](https://developers.withflintpay.com/docs/guides/error-handling.md): Read the Flint error envelope, branch on types and codes, retry safely with idempotency keys, and handle declines as outcomes rather than errors.
- [Going live](https://developers.withflintpay.com/docs/guides/going-live.md): The test-to-production checklist: swap keys, register a live webhook endpoint, confirm readiness, and verify before real money moves.
- [Disputes](https://developers.withflintpay.com/docs/guides/handling-disputes.md): Respond to disputes and chargebacks operationally: monitor via events, meet evidence deadlines, and reconcile the money impact.
- [Securing a headless checkout](https://developers.withflintpay.com/docs/guides/headless-checkout-security.md): 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 your own checkout](https://developers.withflintpay.com/docs/guides/headless-checkout.md): 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.
- [Build your own customer account](https://developers.withflintpay.com/docs/guides/headless-customer-accounts.md): 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.
- [Build a headless storefront](https://developers.withflintpay.com/docs/guides/headless-storefront.md): 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.
- [Idempotency](https://developers.withflintpay.com/docs/guides/idempotency.md): Retry any write safely with idempotency keys. How replays, conflicts, key scoping, and the 24-hour replay window work on the Flint API.
- [Images](https://developers.withflintpay.com/docs/guides/images.md): Add durable, responsive images to products, variants, bundles, subscription plans, payment links, and merchant branding.
- [Inventory](https://developers.withflintpay.com/docs/guides/inventory.md): Stock a location, sell a tracked variant, and follow one unit from receipt through a paid, fulfilled order.
- [Invoicing](https://developers.withflintpay.com/docs/guides/invoicing.md): Bill a specific customer for a specific amount. Flint supports hosted or automatic collection, tracks every attempt, and renders the PDF.
- [LLM integration](https://developers.withflintpay.com/docs/guides/llm-integration.md): Give AI coding agents one URL with Flint Pay schemas, docs, and integration conventions.
- [Manual capture](https://developers.withflintpay.com/docs/guides/manual-capture.md): Place a hold on a card with delayed capture, then capture in full or in part, or cancel to release the hold.
- [MCP server](https://developers.withflintpay.com/docs/guides/mcp-server.md): Connect an AI coding agent to the Flint docs over the Model Context Protocol for live search and API reference lookups.
- [Flint billing](https://developers.withflintpay.com/docs/guides/merchant-billing.md): 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.
- [Migrating from Square](https://developers.withflintpay.com/docs/guides/migrating-from-square.md): Migrate common Square payment flows to Flint for hosted checkout, embedded card payments, cards on file, subscriptions, invoices, refunds, and webhooks.
- [Migrating from Stripe](https://developers.withflintpay.com/docs/guides/migrating-from-stripe.md): Migrate common Stripe integrations to Flint for subscriptions, one-time payments, payment links, invoices, saved cards, refunds, and webhooks.
- [Money & currency](https://developers.withflintpay.com/docs/guides/money-and-amounts.md): How Flint represents money: integer minor units, the amount and currency object, and when to use unit_price_money vs amount_money.
- [Node SDK](https://developers.withflintpay.com/docs/guides/node-sdk.md): Install and use the official @flintpay/node package for typed Flint Pay integrations in Node.js and TypeScript.
- [Statuses & lifecycles](https://developers.withflintpay.com/docs/guides/object-lifecycles.md): Every status value across orders, payments, refunds, invoices, subscriptions, fulfillment, and returns, which ones are final, and how to read them without guessing.
- [Order activities](https://developers.withflintpay.com/docs/guides/order-activities.md): Read an order's human-readable history log to render a timeline and debug what happened, without treating it as a source of truth.
- [Why Flint is orders-first](https://developers.withflintpay.com/docs/guides/orders-first.md): Every Flint payment settles against an order. What the order records, how checkout sessions, payment intents, invoices, and payment links attach to it, and when a bare payment intent is the better choice.
- [Overview](https://developers.withflintpay.com/docs/guides/overview.md): What the Flint API does, the objects you work with, the conventions every request shares, and where to start.
- [Pagination](https://developers.withflintpay.com/docs/guides/pagination.md): 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.
- [Partner app installs](https://developers.withflintpay.com/docs/guides/partner-app-installs.md): Build an installable Flint partner app, send merchants through hosted OAuth install, exchange install tokens, and subscribe to lifecycle webhooks.
- [Payment links vs checkout sessions vs invoices](https://developers.withflintpay.com/docs/guides/payment-links-vs-checkout-sessions-vs-invoices.md): Three hosted ways to collect payment, one orders-first engine underneath. Decide in two questions, see the boundaries, and learn how to combine them.
- [Payment links](https://developers.withflintpay.com/docs/guides/payment-links.md): Create a reusable hosted checkout URL you can share anywhere. Sell products, collect donations, ticket events, and start subscriptions with no frontend code.
- [Processing fees](https://developers.withflintpay.com/docs/guides/processing-fees.md): What Flint charges to process a payment, when the fee becomes final, and how to read your net on every payment and balance transaction.
- [Promotions](https://developers.withflintpay.com/docs/guides/promotions.md): Build automatic discounts, code campaigns, buy-X-get-Y offers, and stacking rules with Flint promotions.
- [Rate limits](https://developers.withflintpay.com/docs/guides/rate-limits.md): 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.
- [Reconciliation](https://developers.withflintpay.com/docs/guides/reconciliation.md): Tie every settled dollar back to an order and match a bank deposit to the balance transactions that funded it.
- [Refunds](https://developers.withflintpay.com/docs/guides/refunds.md): Issue full, partial, and line-item refunds, track them through their asynchronous lifecycle, and handle the ones that fail.
- [Reports](https://developers.withflintpay.com/docs/guides/reporting.md): Generate versioned CSV reports of orders, payments, Flint billing, balance activity, payouts, and tax, then download the completed file with your API key.
- [Return policies and reasons](https://developers.withflintpay.com/docs/guides/return-policies.md): Write the rules once: windows, who pays return shipping, restocking fees, and what decides itself. Plus the four reason vocabularies and which is which.
- [Return resolutions](https://developers.withflintpay.com/docs/guides/return-resolutions.md): Refunds, exchanges, and replacements: what the buyer gets, what it costs them, when it moves, and how to fix it afterwards.
- [In-store returns](https://developers.withflintpay.com/docs/guides/returns-at-the-counter.md): Create a Return, then process its counter facts atomically with a key you can safely replay.
- [Your first return](https://developers.withflintpay.com/docs/guides/returns-quickstart.md): Receive and refund an item at the counter, or approve a return before the customer sends it back.
- [Receiving and inspecting](https://developers.withflintpay.com/docs/guides/returns-receiving.md): Record what physically arrived, what condition it was in, and where it ended up, from a system that has no authority to refund.
- [Buyer-initiated returns](https://developers.withflintpay.com/docs/guides/returns-self-serve.md): Let buyers start a return themselves: show what is eligible, compare outcomes, print a label, and track the parcel back.
- [Returns](https://developers.withflintpay.com/docs/guides/returns.md): Take merchandise back and settle what the buyer is owed. The Return model, the statuses that answer each question, and which integration to build.
- [Risk controls](https://developers.withflintpay.com/docs/guides/risk-controls.md): Evaluate every payment attempt, author deterministic rules and lists, resolve reviews, and respond to fraud warnings.
- [Sales tax](https://developers.withflintpay.com/docs/guides/sales-tax.md): Calculate tax on orders, supply a tax location, reconcile the result, and control how tax reverses on a refund.
- [Sandboxes & test mode](https://developers.withflintpay.com/docs/guides/sandboxes.md): How your key selects test or live mode, what a sandbox isolates, and how to create, reset, and archive sandboxes for local development, CI, and QA.
- [Server-confirmed payments](https://developers.withflintpay.com/docs/guides/server-confirmed-payments.md): Collect a ConfirmationToken in the browser, confirm through Flint, handle typed client actions, and safely continue manual confirmation.
- [Subscription billing](https://developers.withflintpay.com/docs/guides/subscription-billing.md): Model recurring pricing with plans, start or import subscriptions, control billing schedules, and run the full lifecycle. Trials, renewals as orders, failed-payment recovery, pause, and cancel.
- [Testing](https://developers.withflintpay.com/docs/guides/testing.md): Simulate successful payments, declines, and 3D Secure with test cards or API test tokens, then verify orders, webhooks, refunds, and renewals in your sandbox.
- [Tips & fees](https://developers.withflintpay.com/docs/guides/tips-and-charges.md): 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.
- [Choosing webhook events](https://developers.withflintpay.com/docs/guides/webhook-event-altitude.md): Pick the right Flint webhook event level for reconciliation, fulfillment, dunning, entitlements, saved payment methods, and platform readiness.
- [Webhook event payloads](https://developers.withflintpay.com/docs/guides/webhook-events-catalog.md): Every webhook event Flint can send: what triggers it, what its data payload carries, and which event to build each job on.
- [Webhooks](https://developers.withflintpay.com/docs/guides/webhooks.md): Receive signed event notifications when payments, orders, and subscriptions change, verify Standard Webhooks signatures, and process each one exactly once.

## API reference

- [API keys](https://developers.withflintpay.com/docs/api/api-keys.md): Create and manage Flint Pay API keys for secure server-side authentication.
- [OpenAPI](https://developers.withflintpay.com/docs/api/openapi.md): Download the Flint Pay OpenAPI spec for code generation, agents, SDKs, and API tooling.
- [Developer setup](https://developers.withflintpay.com/docs/api/setup.md): Provision a merchant and mint the first Flint API key, with a browser handoff when account verification needs human input.
- [Users](https://developers.withflintpay.com/docs/api/users.md): User records are not exposed on the external merchant API surface.
- [Webhook delivery](https://developers.withflintpay.com/docs/api/webhook-delivery.md): The contract behind every Flint webhook delivery. Request headers, the event envelope and its fields, the retry schedule, and the ordering guarantee.
- [Orders](https://developers.withflintpay.com/docs/api/orders.md): 26 endpoints
- [Invoices](https://developers.withflintpay.com/docs/api/invoices.md): 26 endpoints
- [Credit notes](https://developers.withflintpay.com/docs/api/credit-notes.md): 11 endpoints
- [Customers](https://developers.withflintpay.com/docs/api/customers.md): 14 endpoints
- [Products](https://developers.withflintpay.com/docs/api/products.md): 12 endpoints
- [Categories](https://developers.withflintpay.com/docs/api/categories.md): 5 endpoints
- [Modifiers](https://developers.withflintpay.com/docs/api/modifiers.md): 10 endpoints
- [Bundles](https://developers.withflintpay.com/docs/api/bundles.md): 6 endpoints
- [Promotions](https://developers.withflintpay.com/docs/api/promotions.md): 10 endpoints
- [Returns](https://developers.withflintpay.com/docs/api/returns.md): 17 endpoints
- [Return resolutions](https://developers.withflintpay.com/docs/api/return-resolutions.md): 9 endpoints
- [Return operations](https://developers.withflintpay.com/docs/api/return-operations.md): 13 endpoints
- [Return policies](https://developers.withflintpay.com/docs/api/return-policies.md): 8 endpoints
- [Return reasons](https://developers.withflintpay.com/docs/api/return-reasons.md): 5 endpoints
- [Inventory](https://developers.withflintpay.com/docs/api/inventory.md): 29 endpoints
- [Locations](https://developers.withflintpay.com/docs/api/locations.md): 7 endpoints
- [Delivery configuration](https://developers.withflintpay.com/docs/api/delivery-configuration.md): 29 endpoints
- [Delivery previews](https://developers.withflintpay.com/docs/api/delivery-previews.md): 1 endpoints
- [Delivery quotes](https://developers.withflintpay.com/docs/api/delivery-quotes.md): 4 endpoints
- [Delivery selections](https://developers.withflintpay.com/docs/api/delivery-selections.md): 5 endpoints
- [Delivery revocations](https://developers.withflintpay.com/docs/api/delivery-revocations.md): 2 endpoints
- [Fulfillment records](https://developers.withflintpay.com/docs/api/fulfillment.md): 26 endpoints
- [Payments](https://developers.withflintpay.com/docs/api/payments.md): 7 endpoints
- [Payment methods](https://developers.withflintpay.com/docs/api/payment-methods.md): 5 endpoints
- [Payment method domains](https://developers.withflintpay.com/docs/api/payment-method-domains.md): 4 endpoints
- [Refunds](https://developers.withflintpay.com/docs/api/refunds.md): 4 endpoints
- [Checkout sessions](https://developers.withflintpay.com/docs/api/checkout-sessions.md): 6 endpoints
- [Payment links](https://developers.withflintpay.com/docs/api/payment-links.md): 6 endpoints
- [Disputes](https://developers.withflintpay.com/docs/api/disputes.md): 2 endpoints
- [Risk controls](https://developers.withflintpay.com/docs/api/risk-controls.md): 22 endpoints
- [Money movement](https://developers.withflintpay.com/docs/api/money-movement.md): 14 endpoints
- [Reports](https://developers.withflintpay.com/docs/api/reports.md): 4 endpoints
- [Subscription plans](https://developers.withflintpay.com/docs/api/subscription-plans.md): 5 endpoints
- [Subscriptions](https://developers.withflintpay.com/docs/api/subscriptions.md): 14 endpoints
- [Webhooks](https://developers.withflintpay.com/docs/api/webhooks.md): 15 endpoints
- [API request logs](https://developers.withflintpay.com/docs/api/api-request-logs.md): 3 endpoints
- [Feedback reports](https://developers.withflintpay.com/docs/api/feedback-reports.md): 3 endpoints
- [Merchants](https://developers.withflintpay.com/docs/api/merchants.md): 2 endpoints
- [Flint billing](https://developers.withflintpay.com/docs/api/merchant-billing.md): 4 endpoints
- [Organizations](https://developers.withflintpay.com/docs/api/organizations.md): 9 endpoints
- [Settings](https://developers.withflintpay.com/docs/api/settings.md): 3 endpoints
- [Analytics](https://developers.withflintpay.com/docs/api/analytics.md): 3 endpoints
- [Devices](https://developers.withflintpay.com/docs/api/devices.md): 5 endpoints
- [Sandboxes](https://developers.withflintpay.com/docs/api/sandboxes.md): 6 endpoints
- [Onboarding](https://developers.withflintpay.com/docs/api/onboarding.md): 7 endpoints
- [Merchant account sessions](https://developers.withflintpay.com/docs/api/merchant-account-sessions.md): 2 endpoints
- [Customer sessions](https://developers.withflintpay.com/docs/api/customer-sessions.md): 4 endpoints
- [Customer account](https://developers.withflintpay.com/docs/api/customer-account.md): 45 endpoints
- [Partner apps](https://developers.withflintpay.com/docs/api/partner-apps.md): 9 endpoints
- [Partner OAuth](https://developers.withflintpay.com/docs/api/partner-oauth.md): 3 endpoints
- [Error codes](https://developers.withflintpay.com/docs/errors): every API error code with category, retryability, and fix
- [Card decline codes](https://developers.withflintpay.com/reference/card-decline-codes): every issuer decline code with meaning, retry rules, and customer messaging
- [Test card numbers](https://developers.withflintpay.com/reference/test-cards): test cards and failure triggers for every major processor, including Flint sandboxes
- [Apple Pay domain verification failed](https://developers.withflintpay.com/reference/apple-pay-domain-verification-failed): every cause of a failed domain verification with a curl diagnosis
- [Stripe webhook signature errors](https://developers.withflintpay.com/reference/stripe-webhook-no-signatures-found): the three causes of "No signatures found matching the expected signature for payload" with per-framework fixes
- [How to refund a line item in Stripe](https://developers.withflintpay.com/reference/stripe-refund-line-item): amount-only refunds, credit notes for invoice payments, per-unit proration for Checkout, and refund metadata for accounting reconciliation
- [Does Stripe track inventory?](https://developers.withflintpay.com/reference/stripe-inventory-tracking): no first-party stock counts anywhere in Stripe; the webhook decrement recipe, its five race windows, and reservation-based inventory on Flint
- [Does Stripe have an Orders API?](https://developers.withflintpay.com/reference/stripe-orders-api): both Orders APIs and their retirements, the Climate and Terminal name collisions, what new integrations use instead, and the order-first alternative
- [Stripe as your source of truth](https://developers.withflintpay.com/reference/stripe-as-source-of-truth): payment state is Stripe's to hold and the sale is yours; the domain split, rate-limit and read-allocation math, sync drift traps, and the order-first alternative
- [Payfac-as-a-service, compared](https://developers.withflintpay.com/reference/payfac-as-a-service): Finix, Worldpay (Payrix), Rainforest, Tilled, Stax Connect, Payabli, and Stripe Connect on onboarding, registration, economics, API surface, and go-live claims; vendor-sourced and dated
- [Webhook event types](https://developers.withflintpay.com/docs/webhooks/events): all event types Flint delivers
- [CLI commands](https://developers.withflintpay.com/docs/cli): every flint command with its arguments, flags, and the route it calls

## Blog

- [Collect Deposits With Payment Links](https://developers.withflintpay.com/blog/collect-deposits-with-payment-links.md): How to use payment links for booking deposits without losing structure on the final balance.
- [Next.js and Stripe: What the Tutorials Leave Out](https://developers.withflintpay.com/blog/nextjs-stripe-what-tutorials-leave-out.md): The Next.js Stripe tutorials stop at the Checkout Session and the webhook. Stripe's own docs ask for more, and production asks for more still.
- [Partial Refunds Start With Order Structure](https://developers.withflintpay.com/blog/partial-refunds-start-with-order-structure.md): Why partial refunds are easier when the order, not the charge, is the system of record.
- [Payment Links for Field Services](https://developers.withflintpay.com/blog/payment-links-for-field-services.md): When field-service businesses should use payment links, and when they need orders behind them.
- [Should My SaaS Become a Payfac?](https://developers.withflintpay.com/blog/should-my-saas-become-a-payfac.md): The costs are real numbers, the revenue is a spread, and the threshold everyone quotes depends on who is quoting it. The decision, worked with attributed figures instead of folklore.
- [Stripe vs Order-First Payment APIs](https://developers.withflintpay.com/blog/stripe-vs-order-first-payment-apis.md): When charge-first APIs stop being enough, and why order-first payment infrastructure matters.
- [What's in a Name? Square Items ☕ vs Shopify Products 📦](https://developers.withflintpay.com/blog/whats-in-a-name-square-items-vs-shopify-products.md): Why Flint Pay renamed catalog Items to Products, and how API naming shapes developer mental models.