Skip to content
flint

Commerce API

The API commerce runs on.

Orders, checkout, subscriptions, refunds by line item, and payouts, on one record you never reconcile. You bring the storefront. Flint runs everything between add to cart and money in the bank. Nothing to self-host, no separate processor to contract.

Get free API keys
See it running

free sandbox · no credit card · keys in minutes

OrdersLine items, tax, discounts, and a balance that runs down as money lands./v1/ordersPaymentsCards, wallets, and ACH in. Balances and payouts out. All on the order, not beside it./v1/payment-intentsCheckoutA hosted page, embedded elements, or a reusable link. One order underneath./v1/checkout-sessionsBillingSubscriptions and invoices on the same record, so renewals refund like sales./v1/subscriptionsAgentsScoped keys, MCP servers, and machine-readable safety hints per call./mcp
also in the APIreturnspromotionsinventorypayment linksinvoicescustomer accountsdisputesbalances & payoutsrisk

01The dashboard

The back office is already built.

Payments, orders, returns, payouts, and a developer console from the day you sign up. You still build your storefront; you never build this. It runs on the same public API you integrate, so it can never fall behind.

app.withflintpay.com
Flint dashboard payments list: amounts, statuses, payment ids, card methods and customers for a day of coffee shop orders
Every payment with its method, status and customer, one click from the order it settled. Payments API →

02The checkout

A checkout buyers already know how to use.

Express wallets, cards, bank debit, and Affirm on one page that works on any phone. Point a customer at a hosted page or a reusable link, or embed the payment fields in your own front end.

checkout.withflintpay.com
Hosted checkout in test mode. Every total on screen was computed by the API from line items and ids.
tips, computed server-side
Add a tip
Subtotal$49.00
Tax$4.04
Tip$8.82
Total$61.86
Try it: tips compute on the subtotal, so the buyer never does percentage math. This control is live; the pay buttons on this page are not.
The same checkout on a phone. Wallets first, card fields one tap away.

03After the sale

Refund the croissant, not the order.

One call returns the item, reprorates its tax, restocks it, and updates the balance. Returns, disputes, and renewals run as workflows on the record, not tickets in your queue.

one order, three calls
POST /v1/orders2 line items · tax computed201
POST /v1/checkout-sessionshosted checkout · pays $19.43201
POST /v1/refundsCroissant ×1 · −$5.36201
flintord_1kmn0aExample
Cold brew x 2$13.00
Croissant$4.95
↳ refunded x 1-$5.36
Subtotal$17.95
Tax$1.48
Total$19.43
Paid$19.43
Refunded-$5.36
balance $14.07 · partially_refunded
Partial refund
one record · printed by the API
An order paid and then partly refunded, row by row as each call lands. When it finishes, tear the receipt off and it prints again.

A return, end to end

Buyer starts a return from their portalMon
Policy auto-approves itMon
Items received and restockedThu
$5.36 refunded · tax share includedThu
Buyers track orders, start returns, and manage subscriptions themselves. Ship Flint's account as is, put your brand and your domain on it, or build your own on the same API. Customer accounts →

Renewals bill as orders too, so a subscription refunds like any other sale. Try the billing simulator on the subscriptions page →

04The model

The order is the system of record.

A payments API gives you a charge: an amount, a currency, and nothing about what was sold. The cart, the totals, the tax, and the refund logic all become your code, and your database has to agree with the processor forever.

Coming from a payments processor

With Flint there is one system. Payments, tax, promotions, subscriptions, and refunds compute on the order, with one audit trail. Your database keeps your product; Flint’s keeps the sale. The full payments argument →

Coming from a commerce platform

Same seam, one layer up. You get the catalog and the order, then contract a processor separately and wire it in yourself, and the money lands in a system the order cannot see. Most of them hand you the servers as well. How Flint replaces that stack →

ord_1kmn0aExample

GET /v1/orders/{order_id}

  • status · closed
  • payment_status · paid
  • refund_status · partially_refunded
  • total · $19.43
  • refunded · $5.36

The hero's receipt, the checkout, and the refund above all read and write this record. There is nothing to reconcile, because there is one system.

  • payment_intent

    POST /v1/orders/{order_id}/payment-intents

    Money lands on the order. The amount comes from its balance.

  • checkout_session

    POST /v1/checkout-sessions

    A hosted page over the order the buyer already has.

  • refund

    POST /v1/refunds

    Returns line items, not an amount. Tax follows the item.

  • subscription

    POST /v1/subscriptions

    Each renewal is an order, so it reports like any other sale.

  • dispute

    GET /v1/disputes

    Attached to the payment that attached to the order.

  • payout

    GET /v1/payouts

    The money-out half, on the same ledger as the sale.

The systems you don’t build.

The cart and order service

POST /v1/orders

Tax math, per line item and per refund

order.pricing_amounts.tax_money

The nightly job diffing your DB against the processor

GET /v1/balance-transactions

Support tooling mapping charges back to items

POST /v1/refunds · line_items[]

Retries, ordering, idempotency and replay between services

Idempotency-Key · webhook_event_id

Inventory decrement on payment, restock on refund

POST /v1/inventory-reservations

reviewed 2026-08-07 against the published API · corrections: support@withflintpay.com

The scale of the surface

Settlement runs on Stripe’s rails. The commerce layer is Flint’s.

596
API operations, one set of keys
84
resource families, orders to payouts
186
tools agents call over MCP
20
dashboard sections on day one

every API sample on this page is validated against the published OpenAPI spec at build time

05AI agents

Agents can run the store, safely.

An order is legible to a model in a way a charge never is. Every money-moving call carries machine-readable hints, so an agent knows what is irreversible before it acts, and a human approves anything financial.

An agent is only as capable as the API you hand it.

A payments API gives an agent two verbs: charge and refund. The asks that actually land are bigger, and agents can carry them now. The ceiling is the API, not the model.

Charge my card $19.43.

a payments API can: the verb it has

POST /v1/payment-intents

Refund the croissant, not the whole order.

a payments API cannot: no order to read

POST /v1/refunds · line_items[]

Add a bag of beans before it ships.

a payments API cannot: no order to read

POST /v1/orders/{id}/line-items

Is the dark roast back in stock?

a payments API cannot: no order to read

GET /v1/products

Has my order shipped yet?

a payments API cannot: no order to read

GET /v1/orders/{id}

What sold best this week?

a payments API cannot: no order to read

GET /v1/orders

five of the six need something a payments API does not have: the order

agent_hints · POST /v1/refunds

Side effect
Financial
Human confirmation
Required
Idempotent
Yes, per Idempotency-Key
Terminal states
succeeded · failed

The hint travels with the method, so an agent reads it before it calls. Two MCP servers ship today: one reads the docs, one does the work, and the one that does the work fails closed. The MCP servers and the rest of the agent surface →

06Developers

Four calls from nothing to settled.

Create the order, hand the buyer a hosted page, read the settled state back. Plain HTTP and JSON, a typed Node SDK, and a CLI that streams sandbox webhooks to localhost.

curl
# 1. the order: line items in, totals computed
curl -X POST https://api.withflintpay.com/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "line_items": [ ... ] }'

# 2. a hosted page over that order
curl -X POST https://api.withflintpay.com/v1/checkout-sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "order_id": "ord_1kmn0aExample",
    "redirects": {
      "success_redirect_url": "https://example.com/thanks",
      "cancel_redirect_url": "https://example.com/cart"
    }
  }'

# 3. send the buyer to data.url, exactly as returned

# 4. confirm it from your own backend
curl https://api.withflintpay.com/v1/orders/ord_1kmn0aExample \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK
{
  "data": {
    "order_id": "ord_1kmn0aExample",
    "status": "closed",
    "payment_status": "paid",
    "settlement_amounts": {
      "paid_money":        { "amount": 1943, "currency": "USD" },
      "outstanding_money": { "amount": 0,    "currency": "USD" }
    }
  }
}

The same order, settled. Your backend reads state, never a webhook race.

app.withflintpay.com/developers
Flint developer console: API keys, webhook endpoints, event stream and request logs inside the merchant dashboard
Keys, webhooks, the event stream, request logs, and sandboxes, in the same dashboard as the rest of the business.

Node SDK

npm install @flintpay/node

CLI

brew install flintpay/tap/flint

Live sandbox events, to localhost

flint listen --forward-to http://localhost:8080/webhooks/flint

Quickstart · API reference · Guides

07Pricing

One all-in processing price. The whole stack.

Your approved Flint agreement sets one all-in processing price. Provider costs are not added later as a separate merchant charge. Full details are on the pricing page.

Developer

$0/mo, forever

3.79% + 30¢

cards and wallets · one flat rate, any volume

  • ACH 0.70%, min $1, max $700 per payment
  • Subscriptions & invoicing 0% platform fee
  • Every public API endpoint, including the B2B suite
  • Unlimited test mode, unlimited seats
  • No processing-volume ceiling, no automatic upgrades
  • 20 externally or manually paid orders per month
  • One business · community + email support

For developers, side projects, and businesses validating Flint.

Get free API keys

free sandbox · no card · keys in minutes

Growth

lower rate

3.59% + 30¢

$399/mo, or $299/mo billed annually

  • ACH 0.60%, min $1, max $700 per payment
  • Subscriptions & invoicing 0% platform fee
  • Everything in Developer, at a lower card and ACH rate
  • Unlimited externally or manually paid orders
  • Priority support, launch review, higher rate limits
  • 12-month rate protection with annual billing
  • Pays for itself at ~$200k/mo, or ~$150k/mo billed annually

For growing shops and SaaS, ~$100k–$500k/mo. Month-to-month available.

Get started

$399/mo · $299 annually · switch anytime

Scale

volume

3.39% + 30¢

from $1,499/mo · one-year agreement

  • ACH 0.50%, min $1, max $700 per payment
  • Subscriptions & invoicing 0% platform fee
  • Everything in Growth, at a lower card and ACH rate
  • Named technical contact and incident escalation
  • 99.95% contractual SLA
  • Technical onboarding and payment-rate reviews
  • Contract-term rate protection
  • Net terms, price lists, quotes, and purchase-order workflows
  • Card savings cover the step up from Growth at ~$550k/mo

For high-volume single businesses, ~$400k/mo and up.

Contact sales

a human replies · usually same day

Enterprise

from $2,499/mo

For multiple businesses and submerchants, platform and marketplace payouts, HIPAA or SOC 2 commitments, data residency, and SCIM. Cards, ACH, payouts, and contract terms are all custom on top of the floor. Tell us what you are running and we will price it.

Contact sales

08Limits

What Flint does not do, and why.

Five hard limits. Better you find them now than a week into an integration.

No storefront. Flint has no themes and no page builder. You build and host the storefront; Flint holds the order and collects the money.

No card-present. No terminals, no card readers, no tap to pay, and no promised date for them. Flint fits counter service, online ordering, kiosks, and pay-at-table on the guest’s own phone. If your counter needs a physical reader today, use Square, Toast, or Stripe Terminal.

No bring-your-own processor. Flint provisions and operates its own Stripe-based processing; today you cannot attach a Stripe account you already have. Bringing your own is a work in progress: if your integration depends on it, ask sales where it stands.

No revenue share. The API has no application-fee or revenue-share field, so a platform cannot take a cut of its merchants’ payments. Platforms on Flint charge for their software instead. If a share of each transaction is your business model, talk to sales before you build, not after.

US merchants only. Flint onboards US businesses today, and pricing is in USD. Your buyers are not limited: cards from anywhere in the world work.

FAQ

Questions worth asking first.

Is Flint a Stripe alternative, or built on Stripe?

Flint is the commerce layer most payments APIs leave you to build: orders, catalog, tax, subscriptions, line-item refunds, and payouts on one record. A charge-only API gives you two verbs, charge and refund; Flint gives you the whole transaction. Settlement runs on Stripe's rails underneath, so it is one integration, not a migration to a new processor.

What's the best payment API for AI agents and agentic commerce?

Flint is built for AI agents to transact safely. The order is a semantic record (line items, balances, and refund state, not an opaque charge), so an agent can read exactly what was bought and reason about it. Every money-moving call ships agent_hints: machine-readable side-effect levels, idempotency, required scopes, and terminal states, so an agent knows what’s irreversible before it acts, and anything financial can require human confirmation. It’s plain HTTP and JSON.

How is Flint different from a commerce platform like Medusa, Saleor, or commercetools?

Those platforms model commerce well, but none of them move money: you contract a payment processor separately and integrate it yourself, so the payment ends up in a system the order cannot see and you reconcile the two. Flint is one contract for both, so the money lands on the order as a field rather than arriving from somewhere else. The open-source ones (Medusa, Saleor, Vendure, Magento Open Source) also expect you to run the servers, the database, and the upgrades, or to buy their hosted cloud. Flint is an API: there is no cluster to operate, though you still build and host your own storefront.

Do I need to build my own order or cart service if I use a payments API?

With a charge-only payments API, yes: you end up building the order and cart service, tax math, reconciliation jobs, and refund tooling yourself, then keeping your database and the processor in sync. Flint removes that work. The order is the system of record, so totals, tax, discounts, and refunds compute on one object with one audit trail. There is nothing to reconcile, because there is one source of truth, not two.

Can I refund a single line item instead of the whole charge?

Yes. Flint refunds against the order, line by line: one POST /v1/refunds with the line items returns the money, recomputes the balance and tax, and restocks inventory automatically. A charge-only payments API can only refund an amount, so you map charges back to items by hand. Flint never loses the link between what was charged and what was bought.

Do I have to adopt the whole order model on day one?

No. Charge a card with one POST /v1/payment-intents call and stop there if that’s all you need. Orders, checkout, subscriptions, and payouts are the same API and the same keys when you want them. No migration, no new account.

Does Flint handle tax and totals?

Yes. Flint computes tax per line item on the order, so totals come back correct and refunds return the right tax automatically. You set policy; the order does the math, every time it changes.

How does money out work with Flint?

Flint breaks balances out as available, pending, and reserved; payouts run on the standard schedule; and every movement lands in one transaction ledger, behind the same API as the commerce that generated it.

Is there an SDK or a CLI?

Yes. @flintpay/node is the TypeScript and JavaScript SDK, and @flintpay/cli is a command-line client where every command maps to a documented /v1 route. The CLI forwards live sandbox webhook events to localhost with flint listen, so you can build against real events without a tunnel, and it exposes the same command surface to AI agents over MCP. The API itself is plain HTTP and JSON, so neither is required.

How do I get started with Flint?

Create an account and grab sandbox keys: free, no credit card, no sales call. The quickstart takes you from first order to paid checkout in minutes.

Start with one order.

Free sandbox, no credit card. The record you create today is the same one your dashboard, your buyers, and your agents will read.

Get free API keys
Browse the API reference

Prefer the terminal? npm install -g @flintpay/cli && flint signup creates the account and the sandbox key without leaving it. CLI docs →

POST /v1/orders · everything else follows