# Stripe API for AI agents: payment links, invoices and what each payment really costs

> How an agent creates Stripe payment links and invoices, what Stripe's 2.9% + 30¢ means on a $5 vs $500 payment, and the retries and limits that bite agents.

- Published: 2026-11-01
- Author: AMXP
- Topic: Commerce and pricing
- Tags: #stripe #ai-agents #payments #payment-links #invoicing #idempotency
- Canonical: https://amxp.ai/blog/stripe-api-for-ai-agents

An agent that closes a sale, books a job or bills a client eventually has to ask for money. With
Stripe the safe way is to create a payment link or an invoice and hand the customer a URL: the agent
never sees a card number, and Stripe hosts the page. This guide covers what the call returns, what a
payment costs at $5, $50 and $500, and the two things agents get wrong more than people do: retries
without an idempotency key, and read traffic that quietly eats Stripe's request allocation.

- **2.9% + 30¢** per successful domestic card charge (US list price, October 2026)
- **8.9%** effective fee on a $5 payment (vs 2.96% on $500)
- **24 h** idempotency keys are kept (POST requests only, API v1)
- **100/s** global live-mode rate limit (25/s per endpoint)

## Why this matters for agents

A person creates a handful of payment links a month from the Dashboard. An agent creates one per
order, from code, often in a retry loop, and that changes four things.

**Retries create duplicates unless you say otherwise.** If the connection drops after Stripe
created the link but before your agent read the response, a naive retry makes a second link. Stripe's
fix is the `Idempotency-Key` header: send a random key (a v4 UUID is fine, up to 255 characters) on
every `POST`, and a retry with the same key returns the saved response instead of running again.
Keys are pruned after at least 24 hours, and reusing a key with different parameters is an error
([idempotent requests](https://docs.stripe.com/api/idempotent_requests)). `GET` and `DELETE` ignore
the header.

**Rate limits are per account, not per agent.** Live mode allows 100 requests per second across the
account and 25 per second per endpoint; a sandbox allows 25 per second. Over the limit you get `429
Too Many Requests` with a `Stripe-Rate-Limited-Reason` header saying which limit you hit
([rate limits](https://docs.stripe.com/rate-limits)). Three agents polling the same account share
one bucket.

**Reads are rationed.** Stripe allows an average of 500 read requests per transaction over a
rolling 30 days, with a floor of 10,000 reads a month for every account
([rate limits](https://docs.stripe.com/rate-limits)). An agent that polls `GET /v1/payment_links/{id}`
every 10 seconds to see whether a link was paid burns 8,640 reads a day on a link that may never
convert. Listen for the `checkout.session.completed` webhook instead.

**The API call is free; the payment is not.** Creating a link costs nothing. Stripe charges when the
customer pays, as a percentage plus a fixed amount, so the fee on a small payment is far higher in
percentage terms than on a large one. The arithmetic is below.

Before the agent creates anything, check two values: `livemode` on the response (a test link sent to
a real customer collects nothing) and the currency on the price, because a payment link inherits
its currency from its `line_items` and cannot mix them.

## What Stripe returns

`POST /v1/payment_links` takes `line_items` (required, each a `price` plus `quantity`, up to 20
items) and returns a `payment_link` object ([create a payment link](https://docs.stripe.com/api/payment-link/create)).

| Field | What it is | What surprises people |
| --- | --- | --- |
| `id` | `plink_…` | Stable; store it with the order |
| `url` | `https://buy.stripe.com/…` | Hostname changes to `book.` or `donate.` with `submit_type` |
| `active` | Whether the URL still accepts payment | Deactivating a link does not refund anyone |
| `livemode` | `true` only with a live key | Test links render fine and collect nothing |
| `currency` | Lowercase ISO code | Taken from the price, not a parameter you set freely |
| `metadata` | Your key-value pairs | Copied onto every Checkout Session the link creates |
| `line_items` | What is being sold | Not returned by default; pass `expand[]=line_items` |
| `payment_intent_data` | Settings for the resulting PaymentIntent | `null` unless you set it |
| `invoice_creation` | Post-purchase invoice for one-time payments | `enabled: false` by default |
| `restrictions` | Limit on completed sessions | `null` unless set; use it for one-off orders |

Two things are easy to miss. The object has no "paid" field: a payment link is a reusable page, and
each payment creates a separate Checkout Session, so payment status lives there, not on the link
([Payment Link object](https://docs.stripe.com/api/payment-link/object)). And `price_data` lets the
agent create the product and price inline instead of referencing a `price_…` ID, which is simpler
for one-off quotes but creates a new Product in your account on every call
([Payment Links API](https://docs.stripe.com/payment-links/api)).

For invoices the shape is different: create the invoice, add invoice items, then finalize it. Until
finalization nothing is sent and nothing is owed. Stripe's own [MCP server](https://docs.stripe.com/mcp)
exposes exactly that sequence (create, add items, finalize, void, mark uncollectible), which is a
good checklist for what an invoicing agent needs.

## The economics

Stripe's fees depend on the country of your Stripe account. On the
[US pricing page](https://stripe.com/pricing), as of October 2026:

- Domestic cards: 2.9% + 30¢ per successful transaction.
- International cards: + 1.5%. Currency conversion: + 1% more.
- ACH Direct Debit: 0.8%, capped at $5.00.
- Stablecoin payments: 0.8% per successful transaction, a promotional rate through January 1, 2027.
- Invoicing Starter: 0.4% per paid invoice. Post-payment invoices on links: 0.4%, capped at $2.00.
- Instant Payouts: 1.5% of volume, minimum 50¢. Standard payouts are free.
- No setup or monthly fees.

The UK page, for comparison, lists 1.5% + 20p for standard UK cards, 2.8% + 20p for premium cards,
3.15% + 20p for international cards plus 2% for conversion, and Instant Payouts at 1% with a 40p
minimum ([UK pricing](https://stripe.com/gb/pricing)). Stripe serves the page for the country it
detects, so check which one you are reading.

The fixed 30¢ is what makes small payments expensive:

- $5 payment: 2.9% × $5 = $0.145, plus $0.30, is $0.445, or 8.9%.
- $20 payment: $0.58 + $0.30 = $0.88, or 4.4%.
- $50 payment: $1.45 + $0.30 = $1.75, or 3.5%.
- $500 payment: $14.50 + $0.30 = $14.80, or 2.96%.

**Effective Stripe fee by payment size** (US domestic card pricing, 2.9% + 30¢, October 2026)

| Item | Value |
| --- | --- |
| $5 | 8.9% |
| $20 | 4.4% |
| $50 | 3.5% |
| $500 | 2.96% |

Source: [Stripe pricing](https://stripe.com/pricing). Computed from the list price: (2.9% × amount + $0.30) ÷ amount.

The multipliers stack. A $50 payment from an international card with currency conversion is
2.9% + 1.5% + 1% = 5.4%, so $2.70 + $0.30 = $3.00, or 6.0%. The same $50 by ACH is 0.8% = $0.40.
If your agent lets the customer choose, the payment method decides the margin.

**Stripe fee on a single $50 payment, by path** (US list prices, October 2026)

| Item | Value |
| --- | --- |
| Domestic card | $1.75 |
| International card | $2.50 |
| Intl + conversion | $3 |
| ACH Direct Debit | $0.4 |
| Stablecoin (promo) | $0.4 |

Source: [Stripe pricing](https://stripe.com/pricing). Computed from the list price for each method; ACH and stablecoin have no fixed cent fee.

Worked month: an agent sells 400 items at $20 through payment links. Fees are 400 × $0.88 = $352
on $8,000 collected, 4.4%. Bundle the same demand into 200 orders at $40 and the fees are
200 × ($1.16 + $0.30) = $292. The 30¢ is per transaction, so fewer, larger payments cost less.

Money arrives on a 2-business-day schedule for US accounts, with the first payout typically taking
7 to 14 days ([payouts](https://docs.stripe.com/payouts)). An agent that reports "paid" the moment
the session completes is right about the sale and wrong about the bank balance.

Through AMXP, `inspect` shows what the API call itself costs before the agent runs it. Stripe's
processing fees on the money collected still apply and are unchanged.

## How to call it from your agent

Once AMXP opens, the flow is the same three steps as any other tool: find the Stripe operation,
read its schema and price, then run it with Stripe's own parameter names.

```ts
const [tool] = await amxp.discover({ query: "create a payment link", provider: "stripe" })
const spec = await amxp.inspect(tool.id) // schema, price per call, required fields

const run = await amxp.execute(tool.id, {
  line_items: [{ price: "price_1MoBy5LkdIwHu7ixZhnattbh", quantity: 1 }],
  after_completion: { type: "hosted_confirmation" },
  restrictions: { completed_sessions: { limit: 1 } }, // one order, one payment
  metadata: { order_id: "ord_1042" },
}, { idempotencyKey: "ord_1042-link" })

// run.output.url -> "https://buy.stripe.com/..."
// run.output.livemode -> must be true before you send it
```

The direct call for comparison, with the idempotency key you should never leave out:

```bash
curl https://api.stripe.com/v1/payment_links \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Idempotency-Key: ord_1042-link" \
  -d "line_items[0][price]=price_1MoBy5LkdIwHu7ixZhnattbh" \
  -d "line_items[0][quantity]=1" \
  -d "restrictions[completed_sessions][limit]=1" \
  -d "metadata[order_id]=ord_1042"
```

Stripe also ships its own agent tooling: a remote MCP server at `https://mcp.stripe.com`, agent
skills and a plugin installed with `npm install -g @stripe/cli` and `stripe agent setup`
([agents](https://docs.stripe.com/agents)). The MCP server uses generic `stripe_api_read` and
`stripe_api_write` tools rather than one tool per endpoint, so it does not flood the model's
context, and some actions, such as creating a refund, need a person to approve them in the
Dashboard within 24 hours. From December 2026 it stops accepting full-access secret keys and
restricted keys without the Agent tag; use OAuth or an agent API key
([Stripe MCP](https://docs.stripe.com/mcp)).

If your agent is the one being paid, Stripe's [machine payments](https://docs.stripe.com/payments/machine)
accept per-call payments over MPP and x402. The minimum is $0.50 for card payments through Shared
Payment Tokens and 0.01 USDC for stablecoins, which is the number that decides whether a per-call
price is even possible on cards.

## What most people get wrong

1. **Retrying a `POST` without an idempotency key.** A timeout after Stripe processed the request
   means a second link, invoice or charge. Fix: generate a key per logical action, send it on every
   `POST`, and reuse it on retry. Stripe compares parameters and rejects a mismatch.
2. **Polling for payment.** `GET` requests are capped at 500 per transaction on a 30-day average.
   Fix: subscribe to `checkout.session.completed` and `invoice.paid` webhooks and treat the payment
   link as write-once.
3. **Sending a test-mode URL.** `livemode: false` links look identical to customers and collect
   nothing. Fix: assert `livemode === true` before the URL leaves the agent, and keep the live key out
   of development environments.
4. **Reusing a link meant for one order.** Links are reusable by default, so a forwarded URL can be
   paid twice. Fix: set `restrictions.completed_sessions.limit` to 1, or deactivate the link
   (`active: false`) when the order closes.
5. **Pricing per call below the fixed fee.** At $0.50 the card fee is $0.3145, 63% of the payment.
   Fix: batch small charges into a larger one, use ACH or stablecoins where the fee is a flat
   percentage, or invoice at the end of the period.

## When to use something else

- **Your own Stripe account and keys.** If you already run on Stripe, connect the agent directly or
  through Stripe's MCP server. Payments, customers and payouts live in your account either way, and
  for an agent that only ever talks to Stripe, AMXP adds a hop without adding a capability. AMXP
  earns its place for the tools around the payment: enrichment, messaging, data.
- **[Crossmint](/tools/crossmint)** when the agent needs to hold a wallet and move stablecoins
  onchain rather than collect a card payment on a hosted page.
- **[QuickNode (x402)](/tools/quicknode-x402)** as the other direction: a service your agent pays
  per request over x402, with no account.
- **A Checkout Session instead of a payment link** when you need a single-use page with a
  `success_url` and an expiry, rather than a reusable link. It is the same Stripe account and the
  same fees.

## Common questions

### Can an AI agent take a card payment with Stripe?

It can create the request, as a payment link, Checkout Session or invoice, and the customer
completes payment on Stripe's hosted page. Card data never reaches the agent or the model.

### How much does Stripe charge per transaction?

In the US, 2.9% + 30¢ for domestic cards, plus 1.5% for international cards and 1% for currency
conversion, as of October 2026. On a $20 payment that is 88¢; on a $5 payment it is 8.9% of the
amount.

### Does Stripe have an MCP server?

Yes, at `https://mcp.stripe.com`, with OAuth or agent API keys, and a plugin that installs it with
Stripe's agent skills. Refunds and money movement need human confirmation.

### Can I call Stripe through AMXP today?

Not yet. AMXP is in private preview, and its API, CLI and MCP server are not public. The flow above
is how it works through AMXP once it opens.

## References

1. [Create a payment link (API reference)](https://docs.stripe.com/api/payment-link/create), Stripe
2. [The Payment Link object](https://docs.stripe.com/api/payment-link/object), Stripe
3. [Payment Links API guide](https://docs.stripe.com/payment-links/api), Stripe
4. [Stripe pricing (United States)](https://stripe.com/pricing), Stripe
5. [Stripe pricing (United Kingdom)](https://stripe.com/gb/pricing), Stripe
6. [Idempotent requests](https://docs.stripe.com/api/idempotent_requests), Stripe
7. [Rate limits](https://docs.stripe.com/rate-limits), Stripe
8. [Receive payouts](https://docs.stripe.com/payouts), Stripe
9. [Model Context Protocol (MCP)](https://docs.stripe.com/mcp), Stripe
10. [Agents and AI on Stripe](https://docs.stripe.com/agents), Stripe
11. [Machine payments](https://docs.stripe.com/payments/machine), Stripe