dashcommerce
Get started
← Documentation

Documentation

Stripe setup

What DashCommerce uses

DashCommerce v0.1.x supports two checkout modes:

  • Payment Element (embedded) — stays on your domain, customer never leaves the site, full control of the checkout page design. Includes Apple Pay, Google Pay, Link, and all Stripe-supported BNPL methods. 3DS 2 and SCA handled automatically.
  • Stripe Checkout (hosted) — lowest PCI scope, customer redirects to Stripe's hosted checkout page, returns to your success URL. Simpler to audit; slight UX tradeoff.

Subscriptions and Connect follow Stripe's native primitives. Toggle modes in plugin settings. For most teams, Payment Element is the default recommendation.

Test mode first

In the Stripe Dashboard , stay in test mode until checkout flows are solid. Use Stripe's test card numbers to exercise success, decline, 3DS, and subscription renewal paths before flipping to live mode.

Create restricted API keys appropriate for server-side use only — never expose secret keys in client bundles or commit them to a public repo. The Stripe dashboard's Developers → API keys page lets you create a restricted key with only the scopes DashCommerce needs (Customers, PaymentIntents, Subscriptions, Invoices, Refunds, and webhooks).

Where keys go in EmDash

After installing DashCommerce, open /_emdash/admin and paste your Stripe test keys into DashCommerce → Settings (wording may evolve slightly across releases). The admin is part of your EmDash instance — you are not configuring Stripe on dashcommerce.dev itself.

Webhooks

Production stores need Stripe webhooks pointed at the HTTP endpoint EmDash/DashCommerce exposes for your deployment (exact path and signing secret vary by version — check the current CHANGELOG and server logs). For local development, forward events with the Stripe CLI: 

stripe listen --forward-to localhost:4321/api/stripe/webhook

Every webhook handler is idempotent via unique-indexed Stripe event IDs — replaying a webhook cannot double-process an order. Stripe's at-least-once delivery is safe to rely on.

Subscriptions

DashCommerce Subscriptions are Stripe Subscriptions — not an abstraction on top. Trial periods map to trial_period_days or trial_end. Proration on upgrade or downgrade follows Stripe's standard proration model. Dunning retries are configurable in the Stripe dashboard (Settings → Billing → Subscriptions and emails) and DashCommerce sends its own transactional emails on subscription lifecycle events.

Sign-up fees are implemented as one-time line items on the first invoice. Pause/resume uses Stripe's pause_collection API. Cancellation can be immediate or at-period-end; DashCommerce defaults to at-period-end to preserve paid access.

Connect (marketplaces)

Marketplace payouts use Stripe Connect. Each vendor onboards with a Connect account (Express or Standard depending on your configuration). Payments use transfer_data.destination to route funds and application_fee_amount to take a platform fee. DashCommerce exposes vendor admin surfaces — invite, activate, view payout status — but Stripe's dashboard remains the source of truth for 1099s, disputes, and detailed payout reporting. See DashCommerce for marketplaces.

Tax

The product roadmap includes optional Stripe Tax integration for automatic tax calculation. Until you enable it, treat tax lines as something you validate explicitly for your jurisdiction — especially in the EU and US. DashCommerce is not a Merchant of Record; tax liability remains yours.

If global tax compliance is your primary requirement, see DashCommerce vs Lemon Squeezy — Lemon Squeezy acts as MoR and handles VAT/sales tax globally.

FAQ

What Stripe products does DashCommerce use?
Payment Intents + Payment Element for checkout (card, Apple Pay, Google Pay, Link, BNPL, saved methods, 3DS 2/SCA). Stripe Checkout is supported as a hosted alternative with lower PCI scope. Stripe Subscriptions for recurring billing. Stripe Connect for marketplace payouts. Stripe Tax is planned for automatic tax calculation. Stripe Radar works passively — fraud signals apply to every Payment Intent.
Do I need a Stripe account to use DashCommerce?
Yes. DashCommerce is Stripe-native — it does not abstract Stripe behind a gateway layer and has no alternative payment processor in core. Create a Stripe account at dashboard.stripe.com, start in test mode, activate live mode when checkout flows are proven.
Where do Stripe keys go in EmDash?
After installing DashCommerce, open /_emdash/admin and paste your Stripe test keys into DashCommerce → Settings. The admin is part of your EmDash instance — you are not configuring Stripe on dashcommerce.dev itself. Never commit secret keys to a public repo or expose them in a client bundle.
What about webhooks?
Production stores need Stripe webhooks pointed at the HTTP endpoint EmDash/DashCommerce exposes for your deployment. Exact path and signing secret vary by version — check the current CHANGELOG and your server logs. For local development, use stripe listen --forward-to localhost:4321/api/stripe/webhook to forward events when testing subscription lifecycle or refunds.
Is every webhook idempotent?
Yes. Every webhook handler uses the Stripe event ID as a unique index in the database — replaying a webhook (which Stripe sometimes does at least-once) cannot double-process an order, double-charge a subscription, or double-issue a refund. This is non-negotiable for production commerce and is wired in core.
Can I use Stripe Checkout instead of embedded Payment Element?
Yes. DashCommerce supports both modes. Stripe Checkout is the hosted flow — lower PCI scope, simpler audit, slight UX tradeoff (separate domain). Payment Element is the embedded flow — stays on your domain, full control of checkout page design. Toggle in plugin settings. For most teams, Payment Element is the default recommendation.
What about 3DS 2 and SCA?
Stripe Payment Element handles 3DS 2 / SCA authentication automatically based on issuer and region rules. You do not need to integrate 3DS logic yourself — Stripe prompts the customer when required and returns the authenticated PaymentIntent. DashCommerce confirms the PaymentIntent state before creating the order.
What about tax?
Flat-rate tax is supported by default in settings. Stripe Tax integration is on the roadmap and can be wired with one environment variable when ready. Until you enable it, validate tax lines explicitly for your jurisdiction — especially in the EU and US. DashCommerce is not a Merchant of Record; tax liability remains yours.
What Stripe fees apply?
Stripe's standard processing fees apply — 2.9% + 30¢ per transaction in the US, different rates elsewhere, negotiable at scale. DashCommerce charges no additional platform fee. If you use Stripe Connect for a marketplace, Stripe's Connect fees apply on top (typically 0.25% + 25¢ on top of processing).
Can I use multiple Stripe accounts?
Not in core v0.1.x. DashCommerce assumes one Stripe account per installation. If you run multiple stores with separate Stripe accounts, deploy separate DashCommerce installations.