Stripe agent-toolkit paidTool: how to get structured checkout JSON and parseable URL?

Question

In stripe/agent-toolkit's paidTool, the checkout response is plain text like "Payment required! ... https://checkout.stripe.com/c/pay/ (opens external site)...", which is hard for an AI agent to extract. One-time payment products reportedly fail to create a checkout (only subscriptions work), and there was no description field to give the agent context. What is the new return shape and how should I use it?

Originally asked on GitHub: https://github.com/stripe/ai/issues/92

AgentArmorHQ team · Accepted Answer

Status: the issue was closed as completed after the maintainer showed a new interface in PR #95, where the paid tool can "pass and support all checkout options directly." The proposed return when payment is required is structured JSON:

```json
{
  "status": "payment_required",
  "data": {
    "paymentType": "usageBased",
    "checkoutUrl": "https://checkout.stripe.com/c/pay/...",
    "paymentReason": "You get 3 free generations, then we charge 10 cents per generation."
  },
  "error": null
}
```

So instead of parsing a sentence for the URL, the agent can read `data.checkoutUrl`, and `data.paymentReason` carries the context that the issue reporter wanted as a description. The maintainer's statement that all checkout options can be passed directly suggests the one-time payment case is covered, but the thread does not specifically confirm that one-time payments were fixed.

Until that change is in your version, the workaround from the thread was to embed instructions and context in the existing `paymentReason` option, e.g. `"METER INFO: Your first 3 additions are free, then we charge 10 cents per addition. ... CHECKOUT_URL:"`. That helps the agent understand the pricing and tells it to open the checkout URL in the browser, but the response is still not structured JSON.

AgentArmorHQ team · Answer

**What a GitHub user tried on GitHub** (Outcome unclear)

The reporter listed three problems: no description field for the agent, checkout creation fails for one-time payments (only subscriptions work), and the returned Stripe URL is embedded in a sentence that is hard to extract.

Source: https://github.com/stripe/ai/issues/92

AgentArmorHQ team · Answer

**What @iannuttall tried on GitHub** (Partly worked)

A user showed their current paidTool setup with priceId, successUrl, paymentReason, and meterEvent, and put METER INFO plus a CHECKOUT_URL marker in paymentReason to guide the agent.

Source: https://github.com/stripe/ai/issues/92#issuecomment-2869658061

AgentArmorHQ team · Answer

**What @matv-stripe tried on GitHub** (Outcome unclear)

The maintainer proposed a structured JSON return with status, paymentType, checkoutUrl, paymentReason, and error, and said the interface can pass and support all checkout options directly. The issue was closed as completed after this proposal.

Source: https://github.com/stripe/ai/issues/92#issuecomment-2874348953

Stripe agent-toolkit paidTool: how to get structured checkout JSON and parseable URL?

4 answers

Add your answer or comment