Skip to main content
Glama

payments_checkout

Create a Stripe Checkout Session for a project. Once the project owner has onboarded, funds settle to their connected account; the response's fee_percent is the platform fee on the session (current rate at /v1/pricing) and Stripe's standard processing fee also applies. Before onboarding, env='dev' checkouts run on the platform's own Stripe test account with no Connect destination — the response includes is_stand_in: true and platform_fee_cents: 0 so card 4242 4242 4242 4242 succeeds end-to-end. env='prod' returns 412 until the owner finishes onboarding. Supports mode='payment' | 'subscription'.

Three payment bases (exactly one per call): line_items (ad-hoc), quote_id (a stored quote from a payments quote — server supplies the amount; one-time only, and may compose with calendar_hold_token + booking_id for an atomic booking checkout), or plan (a catalog plan slug — the /sw.billing subscribe path).

Plan tracking: a developer may pass metadata={"app_user_id":"","plan":""}; app functions use sw.payments.checkoutForUser for their verified signed-in user. The platform binds the user, price, payment account and test/live mode before checkout, then verifies the payment before granting the selected plan. Live subscriptions keep access during payment retries and lose it when unpaid, paused, canceled or expired. Test purchases are recorded separately and never unlock live access; auth and billing readers currently show live access only. Redeploy older apps normally to enable the runtime user proof. Historical or unmatched payments require reconciliation; metadata alone never grants a plan.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project_id": "<project_id>",
      "success_url": "<success_url>",
      "cancel_url": "<cancel_url>"
    },
    "name": "payments_checkout"
  }
}

Input Schema

NameRequiredDescriptionDefault
envNo'dev' (default — test-mode Stripe; works without onboarding) or 'prod' (real Stripe; requires the project owner to have onboarded).
modeNo'payment' for one-time or 'subscription' for recurring.
planNoCatalog-plan checkout: a catalog plan slug (the <PricingTable> / sw.billing subscribe path). It replaces line_items to check out a predefined plan.
metadataNoOptional key/value object forwarded to the Checkout Session. Accepts a native object; a JSON-stringified object is also accepted. A developer may pass {"app_user_id":"<id>","plan":"<slug>"} to bind a plan checkout. App functions use checkoutForUser with the verified caller. Test purchases never change live access; the stored checkout and confirmed payment control the grant.
quote_idNoQuote-based checkout: the id from a payments quote. The stored quote supplies the line items and amount (server-authoritative), so line_items is not accepted alongside it. One-time payment only (not subscription). May be combined with calendar_hold_token and booking_id for an atomic booking checkout.
booking_idNoOptional booking id to link this checkout to a booking record (composed with quote_id).
cancel_urlYesRedirect URL on cancellation.
line_itemsNoArray of line_items. Accepts a native JSON array; a JSON-stringified array is also accepted. Each item is EITHER {price:"<stripe_price_id>", quantity} OR {amount:<integer cents>, currency:"usd", name:"<label>", quantity}. For an ad-hoc price use the {amount, currency, name} trio — a nested Stripe price object is not accepted.
project_idYesProject ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them).
success_urlYesRedirect URL on successful payment.
customer_emailNoOptional prefilled email for the Checkout page.
calendar_hold_tokenNoOptional calendar-hold token to atomically confirm a held time slot on successful payment (composed with quote_id).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover the mutation/open-world profile, but the description adds substantial behavioral context: funds settle to the connected account, fee_percent reflects the platform fee plus Stripe processing, pre-onboarding dev checkouts are stand-ins with is_stand_in:true and platform_fee_cents:0, and prod fails with 412. It also discloses downstream grant semantics (live subscriptions retain access during retries and lose it when unpaid/paused/canceled/expired; test purchases never unlock live access) and that historical payments need reconciliation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the three payment bases are logically grouped, but the plan-tracking paragraph restates the metadata parameter description nearly verbatim ('Test purchases... never unlock live access' vs 'Test purchases never change live access'), and the reconciliation aside is tangential for a single call. Length is partly justified by 12 params and multi-mode behavior, but there is detectable redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter, open-world mutation with no output schema, the description covers prerequisites, error behavior, fee semantics, and grant rules thoroughly, so an agent can call it correctly. It stops short of describing the primary return payload (checkout session id/URL) needed to actually redirect the user, leaving a gap only partially filled by the fee_percent/is_stand_in mentions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage the baseline is 3, and the description adds real meaning beyond the schema: the 'exactly one of line_items / quote_id / plan' rule is stated as an overarching constraint, quote_id is flagged one-time-only, and env/mode behavior is explained. The remaining per-parameter detail is largely already in the schema, keeping it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: 'Create a Stripe Checkout Session for a project,' and enumerates the three mutually exclusive payment bases (line_items, quote_id, plan), which makes the tool's scope unambiguous. It does not explicitly contrast itself with the payments_* siblings (payments_status, payments_transactions, payments_events), so the differentiation is implicit rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use routing across the three payment paths ('exactly one per call'), states env='prod' returns 412 until owner onboarding, and points app functions to sw.payments.checkoutForUser. It does not name any sibling tool to use for adjacent tasks (e.g., checking session status or viewing transactions), so cross-tool guidance is absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources