Create a Checkout Session on the organization's Stripe account
A Stripe Checkout Session created ON the connected account as a direct charge: mode subscription or payment; line_items each an existing price id on the account or inline price_data (currency, unit_amount in the minor unit, product_name, and recurring {interval, interval_count} in subscription mode); success_url and cancel_url on the project's own hosts (the onboarding-link URL rule); optional customer or customer_email, client_reference_id, metadata (keys beginning run402_ are reserved), automatic_tax {enabled} (the organization's own Stripe Tax registrations apply), subscription {trial_period_days, metadata}, locale, allow_promotion_codes, expires_at. There is no payment-method selection: the organization's own Stripe payment-method settings apply (cards, SEPA Direct Debit where enabled). Run402 stamps run402_project_id, run402_org_id and run402_checkout_id into the session's (and the subscription's) metadata so the Stripe events that follow attribute to this project. The outcome arrives as stripe_checkout_completed (and stripe_invoice_paid for a subscription) on the project events feed, or read it with GET .../checkout-sessions/:checkout_session_id. The session url is never logged or cached. Refusals: 403 STRIPE_ACCOUNT_REQUIRED / STRIPE_ACCOUNT_ONBOARDING_INCOMPLETE (details.requirements) / STRIPE_ACCOUNT_RESTRICTED (details.disabled_reason), 422 VALIDATION_FAILED naming the path (a subscription item without recurring, a payment item with it, reserved metadata), 422 STRIPE_RETURN_URL_NOT_ALLOWED, 502 STRIPE_UPSTREAM_ERROR with Stripe's code and param. Behind the lifecycle gate. Direct charges only: the organization is the merchant of record, Stripe bills it for processing and dispute fees from its own balance, Run402 takes no application fee (platform_fee_bps 0) and never holds, moves, or refunds the money. Refunds and disputes live in the organization's own Stripe dashboard. 503 STRIPE_CONNECT_UNAVAILABLE when the platform's Stripe configuration is absent or Stripe is unreachable.
Request
- Base URL: https://api.run402.com
- URL: https://api.run402.com/projects/v1/{project_id}/stripe/checkout-sessions
- Auth: one of:
- HTTP bearer
- API key in header SIGN-IN-WITH-X
- HTTP bearer
- HTTP bearer
Path parameters
Run402 project ID. Public IDs are not UUIDs.
The project through which the organization's Stripe account is reached. A service_key acts only for its OWN project; principals and grant keys authorize via project.stripe.manage (mutations) or project.read (reads). The account belongs to the project's owning organization, read fresh.
Headers
SIWX auth header — base64-encoded JSON payload containing a signed CAIP-122 (EIP-4361) message. See https://docs.x402.org/extensions/sign-in-with-x.
Optional. The same key with the same body returns the original session (200, deduplicated true); the same key with a different body is 409 IDEMPOTENCY_KEY_REUSED. Forwarded to Stripe as the session's idempotency key.
Request body
Response
Idempotency-Key replay: the original session (deduplicated true).
Example response
{
"project_id": "prj_1741340000_0042",
"next_actions": [
{
"method": "POST",
"path": "/tiers/v1/hobby",
"auth": "x402"
}
]
}Changes
No recorded changes to this operation across all 1 revision of this API.