The ecommerce payment API
that understands what you sell
Traditional payment processing APIs handle a number. They don't know what was purchased, can't compute tax, and can't refund a single item. Flint Pay is an ecommerce payment solution built around the order. Line items, discounts, tax, payments, refunds, and an audit trail, all computed from one object.
You build all of this. You maintain all of this.
Line items, tax, discounts, payments, refunds, audit trail. One call.
The problem
Why payment-first APIs create technical debt for ecommerce
Most ecommerce payment integrations start the same way: create a charge for an amount, stuff an internal order ID into metadata, and move on. It works for the first version.
Then the requirements arrive. Line items for receipts. Tax calculation. Discount codes. Partial refunds. Inventory tracking. An audit trail for compliance. Each requirement becomes a new system you build and maintain alongside the payment processor.
Six months later, you have a payment gateway talking to a homegrown order database talking to a tax service talking to a discount engine. State is split across four systems. A refund requires a spreadsheet. And when someone asks your AI agent to "refund the coffee from Sarah's last order," it sees amount: 3828 and has no idea what to do.
The problem isn't your code. The problem is that payment-first APIs force you to build a commerce layer around a system that doesn't understand commerce.
How Flint Pay works
How Flint Pay's order-first payment integration works
Flint Pay inverts the traditional model. Instead of processing a flat amount and rebuilding context from metadata, you create an order with line items. Everything else (totals, tax, discounts, payment intents, refund tracking, and the audit trail) is computed automatically by the API.
The order is the single source of truth. When you apply a coupon, totals recalculate. When you issue a refund, the balance updates and tax adjusts proportionally. When you query the order, every amount is current, every transition is logged, and the status reflects exactly where the order stands in its lifecycle.
const order = await flint.orders.create({customerId: "cus_01HZ4X8",lineItems: [{name: "Organic Coffee Beans",quantity: 2,unitPriceMoney: { amount: 1999, currency: "USD" },},{name: "Ceramic Pour-Over Mug",quantity: 1,unitPriceMoney: { amount: 2400, currency: "USD" },},],});// order.netAmounts.subtotalMoney → { amount: 6398 }// order.netAmounts.taxMoney → computed// order.netAmounts.balanceMoney → computed
const result = await flint.orders.pay({orderId: "ord_01HZ4X9",paymentSourceTokens: ["tok_visa"],buyerEmail: "sarah@example.com",});// Payment intent created automatically.// Amount derived from order balance.// Receipt email sent on settlement.// Order status → PAID.
const refund = await flint.refunds.create({paymentIntentId: "pi_01HZ4XA",amountMoney: { amount: 1999, currency: "USD" },reason: "REFUND_REASON_REQUESTED_BY_CUSTOMER",idempotencyKey: "ref_sarah_coffee_20250115",});// Order balance recalculated automatically.// Tax adjusted proportionally.// Activity logged: "refund.created".// Status → PARTIALLY_REFUNDED.
What's in the order
Everything your ecommerce payment integration needs in one API
No separate tax service, no discount engine, no reconciliation scripts. The order handles it.
Line items
Every order contains structured line items with names, quantities, SKUs, and prices. Not a flat amount stuffed into metadata.
Automatic tax
Tax computed per item based on nexus rules. The breakdown is included in every order response. No third-party tax service required.
Discounts & coupons
Percentage or fixed-amount coupons with stacking rules, usage limits, and expiration dates. Applied and tracked automatically.
Payment intents from orders
Payment intents are created from orders. Amount, currency, and customer are derived automatically. No amount mismatch risk.
Refunds that make sense
Issue a refund and the order balance, tax, and status recalculate automatically. One API call, not a spreadsheet exercise.
Built-in audit trail
Every mutation is recorded with a timestamp, actor, and delta. Compliance-ready from day one, not bolted on after an incident.
AI-ready responses
Responses include semantic data: what was bought, what can be refunded, available actions. AI agents reason about orders, not opaque amounts.
Deterministic lifecycle
Orders follow a predictable state machine (OPEN → PAID → CLOSED). Status transitions are enforced server-side. No ambiguous states.
Comparison
Flint Pay vs. traditional payment gateways
What you get out of the box with Flint Pay versus what you build yourself on top of a traditional payment API.
| Capability | Payment-first | Flint Pay |
|---|---|---|
Line items Know what was purchased | metadata[order_id] | First-class order fields |
Tax calculation Compute and track tax per item | Build or buy separately | Built-in, per-item breakdown |
Discounts & coupons Apply, stack, and track discounts | Build from scratch | Built-in with stacking rules |
Partial refunds Refund by line item | Manual amount calculation | Refund by line item ID |
Audit trail Track every mutation | Build from scratch | Automatic activity log |
AI agent support Structured data for LLMs | Not possible | Semantic responses + /SKILL.md |
Order state machine Deterministic status lifecycle | Build from scratch | OPEN → PAID → CLOSED |
Totals & balances Auto-computed net amounts | Calculate yourself | Computed on every response |
Built for AI agents
AI-ready payment API: semantic data for LLM agents
When your AI agent queries a traditional payment API, it gets back an amount and a status. It doesn't know what was purchased, whether a partial refund is safe, or what side effects a refund would have.
Flint Pay returns semantic data. An order response includes line items with names and quantities, computed totals, a status that indicates which operations are allowed, and idempotency keys for safe retries. An AI agent can read a Flint order and understand the transaction the same way a human support agent would.
Flint also serves an /SKILL.md endpoint, a machine-readable description of every API surface, field name, and convention. AI agents can read it once to understand the full API without crawling docs.
{"id": "pi_3MqF2e2eZvKYlo2C","amount": 3828,"currency": "usd","status": "succeeded"}// What was purchased? Unknown.// Safe to refund partially? Unknown.// Idempotent? Unknown.
{"id": "ord_01HZ4X9","status": "PAID","lineItems": [{ "name": "Coffee Beans", "qty": 2 },{ "name": "Pour-Over Mug", "qty": 1 }],"netAmounts": { "paid": 6384, "due": 0 },"activity": ["order.created", "payment.captured"]}
Get started
Integrate ecommerce payments in 5 minutes
Create an account and get API keys
Sign up for free. Your test API key is available immediately. No approval process, no waiting.
Create an order with line items
POST a JSON body with your line items, quantities, and prices. The API computes totals, applies tax, and returns a complete order object.
Collect payment
Create a payment intent from the order (amount is derived automatically) or redirect to a hosted checkout session. Stripe handles card processing under the hood.
Ship, refund, or query. It just works
Issue a refund by line item. Query orders by customer. Close settled orders. The order tracks everything.
Keep Exploring
Related pages for ecommerce and checkout flows
These pages connect the ecommerce angle into Flint's broader product story, hosted workflow pages, and comparison content.