stripe.checkout.create_session

Create a Stripe Checkout Session and return the payment URL

Create a Stripe Checkout Session and return the hosted payment URL.

Acts on the CUSTOMER'S OWN Stripe account, authenticated via the org-scoped Stripe connection selected by cloud_connection_uuid.

The caller should redirect the user to session_url to complete payment. On success Stripe redirects to success_url; on abandonment to cancel_url.

Inputs:

• cloud_connection_uuid: Org-scoped Stripe connection UUID (required).
• price_id: Stripe price ID (required), e.g. price_DEF456.
• success_url: Redirect URL after successful payment (required).
• cancel_url: Redirect URL when user cancels (required).
• mode: payment | subscription | setup (optional, default: subscription).
• customer_id: Existing Stripe customer ID (optional).
• quantity: Line-item quantity (optional, default: 1).
• client_reference_id: Caller-owned identifier Stripe echoes back on every webhook event for this session (optional). This is how a payment is mapped back to the end-user who made it — pass the end_user_uuid here and stripe.access.grant-on-payment can grant access without guessing.
• metadata: Arbitrary key-value metadata stored on the session and echoed on webhook events (optional).

Outputs (terminal state_data):

• session_id: str — Stripe Checkout session ID
• session_url: str — hosted payment page URL to redirect the user to
• status: str — initial session status

Connection required: cloud_connection_uuid — the organization's own Stripe account credentials; there is no platform-key fallback.

Overview

Property	Value
Workflow type	Atomic
Library	App-stripe
Version	1.0

Input Schema

Field	Type	Required	Default	Description
cloud_connection_uuid	uuid	Yes	—	Org-scoped Stripe connection (customer's own account)
price_id	string	Yes	—	Stripe price ID
success_url	string	Yes	—	Redirect URL after successful payment
cancel_url	string	Yes	—	Redirect URL when user cancels
mode	string	No	—	payment
customer_id	string	No	—	Existing Stripe customer ID
quantity	integer	No	—	Line-item quantity (default: 1)
client_reference_id	string	No	—	Caller-owned id echoed on webhook events (pass the end_user_uuid to map a payment to a user)
metadata	json	No	—	Arbitrary key-value metadata echoed on webhook events

Output Schema

Field	Type	Required	Default	Description
session_id	string	No	—	—
session_url	string	No	—	—
status	string	No	—	—
cloud_connection_uuid	uuid	No	—	—
cancel_url	string	No	—	—
customer_id	string	No	—	—
mode	string	No	—	—
price_id	string	No	—	—
quantity	integer	No	—	—
success_url	string	No	—	—
client_reference_id	string	No	—	—
metadata	json	No	—	—
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "stripe.checkout.create_session",
  "initial_data": {
    "cloud_connection_uuid": "value",
    "price_id": "value",
    "success_url": "value",
    "cancel_url": "value"
  }
}