Payments

Billing is the highest-risk surface for AI agents. A retry after a dropped connection can charge a customer twice, and an agent re-running its plan can do the same. Invoke makes each charge happen at most once, and it tells you when it can’t know.

Name the charge

Build the idempotency key from what makes the charge unique, usually the invoice. The same key is the same charge:

const paid = await invoke.call({
  tool: "stripe.charge_customer",
  params: { customer_id: "cus_123", amount: 2400, currency: "usd", invoice_id: "inv_881" },
  agentId: "billing-agent",
  idempotencyKey: "invoice:inv_881",
})

If your retry loop, a restarted worker or the agent itself sends it again, the call resolves with status: "duplicate" and the original receipt. No second charge is made.

When the answer is lost

If the connection drops after Stripe got the request, nobody knows yet whether the charge landed, and a charge isn’t safe to re-run blindly. So Invoke doesn’t guess. It holds the charge as unknown, and call() throws OutcomeUnknownError with safeToRetry: false. A retry with the same key is refused, not re-run.

import { OutcomeUnknownError } from "@invokehq/sdk"

try {
  await invoke.call({ tool: "stripe.charge_customer", params, idempotencyKey: "invoice:inv_881" })
} catch (err) {
  if (err instanceof OutcomeUnknownError && !err.safeToRetry) {
    await flagForBilling(err.resolveUrl) // a person checks Stripe
  } else throw err
}

Whoever checks Stripe settles it with an account key:

curl -X POST "$RESOLVE_URL" \
  -H "X-API-Key: $ACCOUNT_KEY" -H "Content-Type: application/json" \
  -d '{"outcome": "happened", "note": "charge found in Stripe"}'

happened commits the charge and seals its receipt. not_happened releases the reserved budget, so an honest retry can run.

Put big charges behind a human

A workspace policy can require approval above an amount:

curl -X POST https://api.invokehq.run/v1/workspaces/$WORKSPACE_ID/policies \
  -H "X-API-Key: $ACCOUNT_KEY" -H "Content-Type: application/json" \
  -d '{"name": "charges over $50 need a human", "effect": "require_approval",
       "match": {"tool": "stripe.charge_customer"},
       "conditions": [{"field": "amount", "op": "gt", "value": 5000}]}'

A charge over the line throws ApprovalRequiredError, and nothing is charged. Pass waitForApproval to wait for the reviewer instead. The receipt records who approved it.

Verify the customer before a refund

Before a refund or any follow-up charge, confirm the customer hasn’t changed since the agent resolved it. POST /state/verify compares what the agent assumed with what is true now:

curl -X POST https://api.invokehq.run/state/verify \
  -H "X-API-Key: $INVOKE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "intent": "issue_refund",
    "required_fields": ["customer_id"],
    "assumed_state": { "customer_id": "cus_123" },
    "current_state": { "customer_id": "cus_123" },
    "conditions": { "customer_id": "cus_123" },
    "on_mismatch": "replan"
  }'

It answers "status": "verified" when the state still matches, and "status": "replan_required" with the mismatched fields when it doesn’t. Act only on verified.

Next steps

TypeScript SDK: every error and what it means
Reconciliation: how Invoke handles unknown outcomes
POST /state/verify: the full API reference

Get Started

Core Concepts

Guides

SDK & CLI

Configuration

Name the charge

When the answer is lost

Put big charges behind a human

Verify the customer before a refund

Next steps

​Name the charge

​When the answer is lost

​Put big charges behind a human

​Verify the customer before a refund

​Next steps

Name the charge

When the answer is lost

Put big charges behind a human

Verify the customer before a refund

Next steps