Build with AI
Your AI can build the store. Give it real commerce.
Describe the store to Claude Code, Cursor, or whatever agent you build with. It reads Flint's live docs, writes against one commerce API, and what it ships takes real orders: totals computed server-side, tax applied, refunds that work, receipts that send.
claude mcp add --transport http flint-docs \
https://developers.withflintpay.com/mcpThe docs MCP server is public and read-only. Your agent searches the guides and pulls exact endpoint schemas instead of guessing field names from memory.
596 operations on one API · 186 tools agents call over MCP · totals computed server-side
01The trap
A payment API makes your AI invent a store.
Ask an agent to add checkout and it will reach for a payment API, charge an amount, and move on. The amount is where the trouble starts: everything that explains it has to be built from scratch, by the model, in the page.
// the model does the money math in the page
const subtotal = items.reduce((s, i) => s + i.price * i.qty, 0);
const tax = subtotal * 0.08; // a guessed rate
const total = subtotal + tax;
// then charges an opaque amount
await stripe.paymentIntents.create({
amount: Math.round(total * 100), // floats become cents
currency: "usd",
});
// then invents the rest of the store:
// an orders table, refund math, receipts,
// and every place those numbers must agreeThe money math lives in generated page code, the charge is an opaque amount, and nothing recorded what was sold. Drifting totals, guessed tax, and unrefundable sales all start here.
{
"data": {
"order_id": "ord_1kmn0aExample",
"status": "open",
"payment_status": "unpaid",
"pricing_amounts": {
"subtotal_money": { "amount": 4100, "currency": "USD" },
"tax_money": { "amount": 328, "currency": "USD" },
"total_money": { "amount": 4428, "currency": "USD" }
},
"settlement_amounts": {
"paid_money": { "amount": 0, "currency": "USD" },
"outstanding_money": { "amount": 4428, "currency": "USD" }
}
}
}One call created this record. Subtotal, tax, total, and the outstanding balance are computed and stored server-side, so nothing depends on arithmetic the model wrote into a component.
The trap compounds in month two. Refund one item, run a sale, charge tax properly, add a subscription: each lands on whatever recorded the sale, and a charge recorded an amount. So each becomes another system to build and another prompt asking the model to invent commerce from memory. Start on the order and month two is more calls to the same object. You deepen the integration; you never rebuild it.
02One object
The order does what the prompt was doing.
Send line items and Flint holds the rest of the sale: what was bought, what it costs, what tax applied, what has been paid, and what is still owed.
curl -X POST https://api.withflintpay.com/v1/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: order-tote-001" \
-d '{
"line_items": [
{ "name": "Canvas tote bag", "quantity": 1,
"unit_price_money": { "amount": 2500, "currency": "USD" } },
{ "name": "Enamel pin", "quantity": 2,
"unit_price_money": { "amount": 800, "currency": "USD" } }
]
}'The idempotency key means the agent can safely retry. Same key, same order, no double charge.
Totals, tax, and balances compute server-side and live on the record.
pricing_amounts · settlement_amountsPayments attach to the order, so every charge knows what it paid for.
POST /v1/orders/{order_id}/payRefunds take line items, and the tax comes back allocated per item.
POST /v1/refundsThe site hears about money as order events, not raw processor noise.
order.paid · order.refundedCatalog, promotions, subscriptions, and inventory hang off the same record when the store grows into them. The commerce API page walks the whole engine.
03The integration
Your agent reads the docs itself.
Flint publishes its surface in the formats AI tools already consume, so the integration step is a prompt, not an afternoon of tab switching.
claude mcp add --transport http flint-docs \
https://developers.withflintpay.com/mcpLive docs search and exact request and response schemas over MCP. Public, read-only, no API key.
developers.withflintpay.com/mcpThe whole public API as one dense file. Paste SKILL.md into CLAUDE.md or a system prompt.
SKILL.mdEvery docs page serves raw Markdown with .md appended, and the corpus ships as one file.
/llms.txt · /llms-full.txtThe OpenAPI spec is public, so generated code and validators work from the same contract the docs do.
api.withflintpay.com/v1/openapi.jsonThere is a second MCP server that acts on your account with your credential. Both, and what the write server refuses to do, are on the MCP page.
04Guardrails
Wrong turns return errors, not payments.
You are going to let a model near money. Flint assumes that and fails closed.
There is no browser key to leak. Every Flint key is a server credential, and the buyer's side is a hosted URL, so the classic generated-code mistake, a secret pasted into the page, has no valid form here.
server-only keysThe key's prefix decides the environment. A test key can only ever act on your sandbox, no matter what the agent asks of it.
sandbox keysWith a live key, every call fails until the agent explicitly acknowledges live mode on that specific call.
LIVE_ACKNOWLEDGEMENT_REQUIREDDestructive commands, and sensitive writes in live mode, fail closed until explicitly confirmed. The server never prompts and never assumes.
CONFIRMATION_REQUIREDThe full gate list, and why the account server runs locally with your credential in the OS keychain, is on the MCP page.
05After launch
You run it from a dashboard, not a prompt.
The agent ships the store. The day to day is yours without it: orders, refunds, payouts, and receipts in a dashboard a human drives.
Refunds are a button, receipts send themselves, payouts run on a schedule, and buyers get a portal for their orders. Webhooks keep the site the agent built current without anyone prompting anything.
06Any stack
Whatever the AI built, it plugs in.
Three depths of integration, matched to what your tool produced. All three end at the same order record.
Hosted checkout
The site links out to a Flint-hosted payment page and the buyer comes back paid. No payment UI to build, which for a generated frontend is the point.
- POST /v1/checkout-sessions
- redirects.success_redirect_url
Your own frontend
Next.js, Vite, or whatever the agent scaffolds: create orders from the backend with plain REST or the Node SDK and take payment where you want it.
- POST /v1/orders
- POST /v1/orders/{order_id}/pay
Payment links
Selling before the site exists. Create a link from the dashboard or the CLI and put it in a bio, a DM, or a QR code.
- POST /v1/payment-links
- GET /v1/payment-links/{payment_link_id}
Start at any depth and move without replatforming: the orders are the same records throughout. Building in Next.js, or in a tool that generates it? The Next.js commerce page walks server actions, route handlers, and webhooks. Building in Lovable, v0, Bolt, or Replit? The AI app builders page covers selling with no backend at all.
07Start
The first prompt.
Connect the Flint docs MCP server, then build me
a small store that sells three products through a
hosted checkout. Create orders on the server with
the sandbox key in my environment, pay one with a
test card, and show me the paid order at the end.The whole loop runs on a sandbox key against test cards, so nothing real can move while you iterate.
Connect the docs server
Install the SDK and the CLI
Then read these
FAQ
Questions worth asking first.
Can I build an online store with Claude Code or Cursor?
Yes. Connect the public docs MCP server, or paste SKILL.md into the agent's context, and ask for the store. The agent works from live endpoint schemas, writes against the REST API with a sandbox key, and can create an order, pay it with a test card, and read the result back without a browser. When it looks right, swap in a live key.
How do I add payments to a site built with an AI website builder?
Use hosted checkout or a payment link. Your site links out to a Flint-hosted payment page and the buyer returns paid, so the generated frontend never renders a card form or touches card data. If the builder gives you a backend, create the order there first; if it does not, a payment link needs no code at all.
Do I need to know how to code?
Less than you would think, and for some setups not at all. Payment links and the dashboard cover selling with no code. For a real storefront, the agent writes the code; what you supply is judgment: what you sell, what it costs, and whether the result is right. Either way the dashboard is how you run things afterwards.
Why not let the AI use a payment API directly?
Because then the model has to invent the store around the charge. A payment API takes an amount and returns a payment, so the totals live in generated page code, tax is a guessed multiplier, and nothing records what was sold, which turns refunds and receipts into a rebuild. On Flint the agent sends line items and the order carries server-computed totals, tax, payment state, and the refund path from the first call.
Is it safe to let an AI agent near payments?
The API is built assuming the model will eventually do something wrong. Key prefixes decide the environment, so a test key cannot touch live money. With a live key, every call fails until the agent explicitly acknowledges live mode on that call, and destructive or sensitive actions fail closed until explicitly confirmed. The wrong call returns a structured error, not a payment.
What happens after the AI launches the store?
You run it like any store. Orders, refunds, payouts, and receipts are in the dashboard, buyers get emailed receipts and a portal for their orders, and webhooks keep the site itself current. The agent stays useful for changes, but nothing day to day requires it.