Hosted action payments for SaaS: how to charge users through CAI's confirmation flow

You run a SaaS that charges $5 per month. A user signs up, and their AI agent tries to call your API. The agent has a CAI wallet. Your API can return HTTP 402 with a payment challenge, the agent calls x402_payment_prepare, and CAI sends the user a hosted confirmation page. The user taps "Approve" on their phone, and the payment settles. No credit card on file. No Stripe setup. No redirect to a third-party billing portal. Just a hosted action URL the user opens, confirms, and the charge goes through.

This is the interactive side of the CAI payment model. While the W12 main article covered payment mandates (automatic recurring charges without per-payment confirmation), this one covers the one-time hosted action flow: what happens when the user needs to approve each charge, and how you as a SaaS operator can accept those payments.

The hosted action flow, from the seller's side

When a CAI wallet user hits a paid endpoint on your service, the flow goes through three stages:

  1. Payment challenge - Your API returns HTTP 402 with a structured payment challenge containing your wallet address, the amount, the chain, and the token you want to be paid in.
  2. User confirmation - The paying agent calls x402_payment_prepare with your challenge. CAI checks the user's balance and, if there's no active mandate covering this merchant, returns a requires_user_confirm: true response with a confirmation_url. That URL is a hosted action page at https://cai.com/act/... where the user approves or rejects the payment.
  3. Execution and settlement - Once the user confirms, the agent calls x402_payment_execute with the attempt_id from the prepare step. CAI executes the custodial transfer, and your wallet receives USDC (or the token you specified) minus a short confirmation window.

The key difference from the mandate flow: every charge goes through the hosted action confirmation. The user sees a page on their phone or desktop that says "Agent X wants to pay $5 to Your SaaS." They confirm, and the payment executes.

What you need on your side

You don't need to integrate a CAI SDK or add a JavaScript widget to your site. The integration is at the API level:

  1. A CAI merchant API key - Sign up at cai.com/app, create an API key with pay or full scope. Your wallet address on the chain you want to receive funds on is your merchant receiving address.
  2. HTTP 402 response format - When an agent hits a paid endpoint without payment, return a 402 response with a JSON body. The x402_payment_prepare call accepts resource_url (the endpoint the agent is trying to reach) and a challenge JSON object with recipient_address, amount, chain, and token. Your 402 response should include or point to this information.
  3. Settlement verification - After the agent retries the request (with the x402 proof), you verify on your side. Call the CAI API's payment_intent_status or wallet_activity_list to confirm the transfer landed. Do not rely solely on transfer_status for merchant-side settlement checking.

What the user sees

When a user's agent encounters your paid endpoint and calls x402_payment_prepare, CAI generates a hosted action URL. The user opens it (on any device, it's a web page) and sees:

  • The merchant domain and what they're paying for
  • The amount in USD and the equivalent in the settlement token
  • The $200/day auto-limit badge (a guardrail that applies to all payments)
  • A confirm button they tap to authorize the charge
  • A new-recipient confirmation step if this is the first time they're paying you

This is the same hosted action infrastructure used for transfers, deposits, and WalletConnect approvals. The user doesn't need to install anything or create an account on your platform. They just confirm on the hosted page.

Guardrails that protect your users

Every payment through CAI's hosted action flow has built-in protections:

  • $200/day auto-limit - No single charge or cumulative daily charges can exceed this without the user adjusting limits in their dashboard
  • New-recipient confirmation - The first payment to any new merchant gets an extra confirmation screen
  • Cash-in-pocket framing - The user sees their available balance at confirmation time, so they know what they're approving
  • Real-time settlement - Once confirmed, the transfer executes on-chain. You can verify it through wallet_activity_list within seconds

These guardrails apply whether the user is paying through the hosted action flow or through a payment mandate. They're not configurable on the merchant side; they're user-side safety mechanisms.

When to use hosted actions vs. payment mandates

If your SaaS charges a fixed amount per billing cycle and the user wants their agent to pay automatically without per-charge prompts, set up a payment mandate. The user creates a mandate on their side with your merchant domain, a daily cap, and an expiration. After that, x402_payment_prepare skips the requires_user_confirm step for charges within the mandate limits.

If your SaaS charges variable amounts (usage-based pricing, one-time purchases, pay-per-call APIs), the hosted action flow is the right model. The user confirms each charge, which gives them control over spending while still being fast enough for real-time API usage.

The two models work together. A user might set a mandate for their monthly $5 subscription but get a hosted action prompt for usage overages or one-time feature purchases.

Honest bounds

This flow works for EVM-compatible stablecoin settlement (USDC on supported chains). Card payments go through a different path (create_onramp_url with MoonPay) and are subject to availability per region. CAI is not a full payment service provider: there are no cart APIs, no order webhooks, no automated inventory management. Settlement confirmation uses wallet_activity_list and payment_intent_status on the CAI API, not a full merchant dashboard.

The x402 seller integration is production-ready for APIs that serve AI agents. For human-facing checkout flows (web storefront, mobile app payment), the hosted action URL can be surfaced in the UI, but the primary design target is agent-initiated payments with human confirmation.