Initialize Payment
Initialize checkout for a plan using a publishable Lumen key. Validates the plan/price, creates or reuses the customer, ensures a PSP customer exists, and returns either a Stripe intent (payment or setup), a Dodo payment link, or creates a free subscription directly when no upfront payment is needed.
Request Body
application/json
Lumen publishable API key
^pk_[A-Za-z0-9]+External user ID from your application (stored as externalCustomerId)
Optional external organization identifier for seat-based plans
Plan ID to subscribe to
^plan_int_[A-Za-z0-9]{22}$Price ID for the subscription
^price_[A-Za-z0-9]{22}$Optional monthly price to allow plan toggles at checkout
Optional yearly price to allow plan toggles at checkout
emailOptional business name for B2B
Tax ID (VAT number, etc.)
Billing address line 1
Billing address line 2
Billing postal/ZIP code
Billing city
ISO 2-letter country code
State/province (required for US tax)
Tax payload returned from /public/calculate-tax
When true, creates an authorization for a linked trial plan instead of billing immediately
Timestamp for the primary seat event to attribute usage
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://api.getlumen.dev/v1/public/payment-init" \ -H "Content-Type: application/json" \ -d '{ "lumenPublishableKey": "pk_test_3yJQYvdr5X6b2F4T9aLk", "userId": "user-48291", "organizationId": "acme-engineering", "planId": "plan_int_6FJ7xXk8Qp9zR2tSa1BcDe", "priceId": "price_6FJ7xXk8Qp9zR2tSa1BcDe", "customerEmail": "[email protected]", "customerName": "Jane Smith", "businessName": "Acme Inc.", "customerAddress": "500 Market St", "customerCity": "San Francisco", "customerStateProvince": "CA", "customerZip": "94105", "customerCountry": "US", "taxData": { "taxableAmount": 12000, "totalTaxCents": 1020, "effectiveTaxRate": 0.085, "jurisdiction": "US-CA", "calculationMethod": "auto", "taxLineItems": [ { "type": "tax", "description": "CA state tax (8.5%)", "subtotalCents": 1020, "taxMetadata": { "taxAuthority": "CA FTB", "taxType": "sales_tax", "jurisdiction": "US-CA", "taxRate": 0.085, "rateSource": "auto", "reasonCode": 1, "fullDescription": "Automatic CA sales tax" } } ] } }'{
"clientSecret": "pi_3Q9q6bLsre2zKYZm1_secret_Qr6uP5Y",
"stripePublishableKey": "pk_test_3yJQYvdr5X6b2F4T9aLk",
"intentId": "pi_3Q9q6bLsre2zKYZm1",
"intentType": "payment_intent"
}{
"error": "Invalid Lumen publishable key"
}{
"error": "You already have an active subscription to this plan (Pro). Please manage the existing subscription to change billing frequency.",
"code": 409,
"existingSubscription": {
"stableSubscriptionId": "sub_5aZHprE8xUWyfDqL2m6zC7",
"planId": "plan_int_6FJ7xXk8Qp9zR2tSa1BcDe",
"planName": "Pro",
"status": "active"
}
}{
"error": "Failed to update customer with Stripe ID. Please contact support."
}