Copilots collapse distance: the user is inside the work when they hit a limit. If you bounce them to a generic billing page without context, you break narrative flow. If you silently fail, you break trust.
This note is for teams shipping agent or embedded copilot experiences on top of credit wallets. You will get UX patterns, timing rules, and a concrete return journey after Stripe Checkout — using Chargly’s MCP tools or SDK equivalently.
What “in-flow” actually means
In-flow top-ups share three properties:
- The user understands why progress stopped (credits, not a vague error).
- The purchase path is one or two steps away, with copy tied to the current task.
- After payment, the same surface updates balance and the user can continue the intent.
When to prompt (before the failure)
Check wallet before high-cost actions: long agent chains, image batches, retrieval-heavy steps. Thresholds should be product-tuned — alerting at 20% remaining is different from blocking at zero.
In-flow top-ups
Surface the problem while the user still has context — not only after a tool error stack they did not write.
Checkout handoff without losing the thread
create_checkout (MCP) or your SDK equivalent returns a Checkout URL. The agent should:
- Explain what pack does in one sentence.
- Provide the link (or button in your UI shell).
- Store enough session metadata to reconnect after redirect — thread id, workspace, or opaque continuation token.
Stripe’s success URL should land back in your host app with parameters you can map to refresh balance and resume.
After payment: webhooks, latency, and honesty
Balances update when Chargly processes the Stripe webhook — usually quickly, not instantaneously. Your UI should tolerate a short “confirming purchase” state instead of flashing stale zeros.
If confirmation takes too long, keep the user informed. Silence reads as broken billing.
Copy patterns that work
Weak: “Payment failed.”
Stronger: “You need more credits to run this agent task. Top up with the Starter pack (~X generations) — you will return here when done.”
Weak: “Error 402.”
Stronger: “Your balance is 12 credits; this step needs 40. Buy credits to continue.”
How Chargly fits
Chargly centralizes pack definitions, Checkout session creation, and wallet credit grants so your agent layer does not re-encode business rules in prompts. The agent’s job is judgment and sequencing; Chargly’s job is authoritative balances and auditable ledger lines.
Top-ups inside agents are still Stripe purchases underneath — compliance, receipts, and refunds stay where finance expects them. The product win is continuity: the user should feel they bought more runway, not that they left the product to “do admin.”