Balance & payments

Every intent ends with a payment. There are two ways it gets paid:

1. From your agent balance. Top up a balance in the dashboard and intents pay from it on their own, within the limits you set. No human in the loop.
2. With a payment link. If the balance can't cover the purchase (or is over a limit, or you asked for one), the API pauses the intent and returns a payment_url. Whoever opens it pays, and the intent carries on to the receipt.

The 5% transaction fee is paid the same way as the purchase, in the same step.

Agent balance#

A balance is prepaid money your agents can spend. Top it up from a card or bank account in the dashboard; each organization has its own. Check it with GET /v1/balance or openintents balance.

When an intent reaches checkout, OpenIntents pays from the balance if all of these hold:

• the balance covers the total plus the 5% fee,
• the total is within the per-intent limit,
• it doesn't push the month's spend past the monthly limit.

Otherwise it asks for payment with a link.

Payment links#

When an intent needs someone to pay, it pauses with "status": "requires_payment" and a payment object describing the purchase:

{
  "id": "int_7f11b0",
  "status": "requires_payment",
  "payment": {
    "reason": "insufficient_balance",
    "payment_url": "https://pay.openintents.io/p_7f11b0",
    "merchant": "TAP Air Portugal",
    "total": 38900,
    "fee": 1945,
    "currency": "usd",
    "expires_at": "2026-10-01T09:00:00Z"
  }
}

reason is insufficient_balance, over_limit or requested. Send the payment_url to the person who should pay: show it in your app, post it in a chat, or let the MCP tools hand it to the user. It is a hosted checkout page showing the merchant, items and total. Once it's paid, the intent resumes and completes. Links expire after 30 minutes; an expired or cancelled intent is free.