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
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | 'dev' (default — test-mode Stripe; works without onboarding) or 'prod' (real Stripe; requires the project owner to have onboarded). | |
| mode | No | 'payment' for one-time or 'subscription' for recurring. | |
| plan | No | Catalog-plan checkout: a catalog plan slug (the <PricingTable> / sw.billing subscribe path). It replaces line_items to check out a predefined plan. | |
| metadata | No | Optional 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_id | No | Quote-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_id | No | Optional booking id to link this checkout to a booking record (composed with quote_id). | |
| cancel_url | Yes | Redirect URL on cancellation. | |
| line_items | No | Array 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_id | Yes | Project 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_url | Yes | Redirect URL on successful payment. | |
| customer_email | No | Optional prefilled email for the Checkout page. | |
| calendar_hold_token | No | Optional calendar-hold token to atomically confirm a held time slot on successful payment (composed with quote_id). |