AI Agent Payment Integration

The payment API designed for AI agents.

Most payment APIs return amount: 3828 and nothing else. Flint returns structured commerce data that LLMs can reason about - line items, computed totals, deterministic states, and a machine-readable spec.

No credit cardFree sandbox forever5 min to first agent
What a payment API returns
{ "amount": 3828, "status": "succeeded" }
// What was purchased? Unknown.
// Partial refund safe? Unknown.
// Tax breakdown? Unknown.
What Flint returns
LLM-ready
{
  "id": "ord_01HZ4X9",
  "status": "PAID",
  "lineItems": [
    { "name": "Coffee Beans", "qty": 2 },
    { "name": "Pour-Over Mug", "qty": 1 }
  ],
  "netAmounts": {
    "subtotal": 3828, "tax": 306,
    "total": 4134, "due": 0
  }
}

The problem

AI agents deserve better than a flat integer.

A customer writes to your AI support agent: "Refund the coffee from my last order." The agent queries your payment API. It gets back { amount: 3828, status: "succeeded" }. What was purchased? No idea. Is a partial refund safe? Impossible to tell.

So your team builds a workaround. The agent calls your internal order database, cross-references with the payment provider, looks up tax records in a third system. Three API calls, two databases, and a prayer that everything is in sync.

This is the fundamental problem with using payment-first APIs as the backbone for AI-powered commerce. The data model was designed for humans reading dashboards, not for language models making decisions.

AI agents cannot reason about what they cannot see. If your payment API returns a number, your agent is flying blind.

See the difference

What your AI agent actually receives.

Same transaction. One API returns a number. The other returns data an LLM can act on.

What a payment API returns to an AI
{
  "id": "pi_3MqF2e2eZvKYlo2C",
  "amount": 3828,
  "currency": "usd",
  "status": "succeeded",
  "metadata": {}
}
// What was purchased? Unknown.
// Can I refund just the coffee? Unknown.
// What is the tax breakdown? Unknown.
// Is this order fully paid? Unknown.
// What actions are available? Unknown.
What Flint returns to an AI
{
  "id": "ord_01HZ4X9",
  "status": "PAID",
  "lineItems": [
    { "name": "Organic Coffee Beans",
      "quantity": 2, "unitPrice": 1299 },
    { "name": "Ceramic Pour-Over Mug",
      "quantity": 1, "unitPrice": 1230 }
  ],
  "netAmounts": {
    "subtotal": 3828, "tax": 306,
    "total": 4134, "paid": 4134,
    "due": 0, "refunded": 0
  },
  "refunds": []
}

Built for LLMs

Why AI agents prefer Flint.

Six properties that make Flint the LLM-friendly payment API your agent needs.

Semantic responses

Every API response includes line item names, quantities, computed totals, and available actions. An LLM reads the response and understands the transaction - no metadata parsing, no second lookup.

Deterministic state machine

Orders follow a strict lifecycle: OPEN, PAID, PARTIALLY_REFUNDED, REFUNDED, CLOSED. Your AI agent can check the status and know exactly which operations are valid without guessing.

Idempotent by default

Every write operation accepts an idempotency key. AI agents can safely retry failed requests without creating duplicate charges, duplicate refunds, or inconsistent state.

Side-effect awareness

Every mutation returns the full updated resource. Your agent sees exactly what changed - adjusted totals, new statuses, recalculated tax - without making a follow-up GET request.

Type-safe SDKs

Generated TypeScript and Python clients with full type definitions. Your agent's tool calls get compile-time validation and autocomplete - no string-guessing field names.

/SKILL.md machine-readable spec

Flint serves a /SKILL.md endpoint - a structured, plain-text description of every API surface, field name, enum, and convention. Your agent reads it once and understands the full API.

Real scenarios

How AI agents use Flint.

From support tickets to autonomous billing - here is what your agent does with structured commerce data.

AI Customer Support

"Refund the coffee from my last order."

  1. 1ListOrders - finds the customer's most recent order
  2. 2Reads lineItems - identifies "Organic Coffee Beans" at $12.99
  3. 3CreateRefund - partial refund for that line item
  4. 4Order auto-updates to PARTIALLY_REFUNDED

AI Shopping Assistant

"Add two more of the candles and apply my birthday coupon."

  1. 1AddLineItems - adds 2× Soy Candle to the open order
  2. 2ApplyCoupon - validates and applies BIRTHDAY20 discount
  3. 3Reads netAmounts - confirms new total with discount applied
  4. 4Agent replies with updated cart summary to the customer

Autonomous Billing

"Downgrade to the starter plan at the end of this cycle."

  1. 1GetSubscription - reads current plan and billing period
  2. 2UpdateSubscription - schedules plan change at period end
  3. 3Reads subscription - confirms effective date and new price
  4. 4Agent sends confirmation email with prorated details

Get started

Integration in 3 steps.

No SDK installation. No webhook configuration. Your agent is live in minutes.

1

Feed /SKILL.md into your agent's system prompt

Fetch https://api.withflintpay.com/SKILL.md and inject it into your agent's context. It now knows every endpoint, field, enum, and convention - no docs crawling required.

2

Give your agent a Flint API key

Create a test API key from the dashboard. Your agent authenticates with a single Bearer token header. No OAuth flows, no session management.

3

Your agent handles commerce

Your agent creates orders, processes payments, issues refunds, and manages subscriptions. Every response is structured data it can reason about - no glue code needed.

agent-bootstrap.ts
const spec = await fetch(
  "https://api.withflintpay.com/SKILL.md"
);
const context = await spec.text();
// Feed the spec into your agent's
// system prompt. It now knows every
// endpoint, field, and enum.
const agent = new PaymentAgent({
  systemPrompt: context,
  apiKey: process.env.FLINT_API_KEY,
});
await agent.handle(
  "Refund the coffee from Sarah's order."
);
// Agent knows: query orders →
// find line item → create refund

Machine-readable spec

/SKILL.md - your agent's API cheat sheet.

Most APIs force an LLM to crawl documentation pages, parse HTML, and guess at conventions. Flint serves a /SKILL.md endpoint - a single, structured plain-text file that describes every API surface in a format optimized for language models.

Your AI agent fetches it once, loads it into context, and immediately understands how to create orders, process payments, issue refunds, and handle every edge case. No documentation crawling. No hallucinated field names.

Semantic responses
Line items, quantities, computed totals in every response
State machine
OPEN → PAID → PARTIALLY_REFUNDED → REFUNDED → CLOSED
Idempotency
Every write operation accepts an idempotency key
Side-effect hints
FINANCIAL, RESOURCE_LOCAL, NONE - agents know the risk level
Human confirmation gates
Flag operations that need approval before execution

Full example

What an agent refund actually looks like.

A real workflow: customer asks to refund one item. Your agent lists orders, reads line items, creates a partial refund, and the order status auto-updates.

handle-refund.ts
// Step 1: Find the customer's latest order
const orders = await flint.orders.list({
  customerId: "cus_01HZ4X9",
  pageSize: 1,
});
const order = orders.orders[0];
// order.status = "PAID"
// order.lineItems = [
//   { name: "Organic Coffee Beans", quantity: 2, unitPrice: 1299 },
//   { name: "Ceramic Pour-Over Mug", quantity: 1, unitPrice: 1230 }
// ]
// Step 2: Find the line item to refund
const coffee = order.lineItems.find(
  (item) => item.name.includes("Coffee")
);
// coffee.totalMoney = { amount: 2598, currency: "USD" }
// Step 3: Create a partial refund
const refund = await flint.refunds.create({
  orderId: order.id,
  paymentIntentId: order.paymentIntentIds[0],
  amountMoney: coffee.totalMoney,
  reason: "REQUESTED_BY_CUSTOMER",
  idempotencyKey: "refund-coffee-" + order.id,
});
// refund.status = "COMPLETED"
// Step 4: Order auto-updates - no extra call needed
// order.status is now "PARTIALLY_REFUNDED"
// order.netAmounts.refunded = 2598
// order.netAmounts.due = 0

Everything included

What your agent gets out of the box.

Every feature your AI agent needs to handle commerce - no plugins, no third-party add-ons.

Line-item-level order data in every response
Computed netAmounts (subtotal, tax, tips, discounts, paid, due)
Deterministic order lifecycle with explicit statuses
Idempotency keys on every write operation
Automatic partial refund tracking and status transitions
Coupon validation and stacking rules enforced server-side
Tax calculation built in - no third-party tax API needed
Cursor-based pagination for listing large datasets
Subscription billing with plan changes and proration
Webhook events for every state transition

AI Payments Benchmark

We built an open benchmark that measures how accurately AI agents complete payment tasks across different APIs - creating orders, processing refunds, handling edge cases. Structured, semantic APIs dramatically reduce agent errors and hallucinations.

View the benchmark

Keep Exploring

Related pages for structured payment data

AI payments only makes sense when the underlying order and checkout model is clear. These pages connect that argument back to Flint's core product surface.

5 minute setup

Give your AI agent a payment API it can understand.

Structured orders, deterministic states, idempotent operations, and a machine-readable spec. Free to start - no credit card required.

No credit card requiredFree sandbox foreverProduction ready in minutes
agent.ts
const spec = await fetch(
  "https://api.withflintpay.com/SKILL.md"
);
const agent = new PaymentAgent({
  systemPrompt: await spec.text(),
  apiKey: process.env.FLINT_API_KEY,
});
await agent.handle("Refund the coffee.");
// Done. Your agent handles commerce.