Skip to main content
Version: 2.0.0

Stripe

Stripe connects Stripe Checkout to the Yui/yStore checkout flow using the official stripe/stripe-php SDK. It registers as a payment method on the storefront, redirects the customer to a Stripe-hosted Checkout Session, and reconciles the result back into the order through a signed webhook. Beyond the base payment flow, it adds a Stripe section to the Craft control panel with a dashboard, payment history, subscription management, refunds, dispute handling, and the Stripe Customer Portal.

What it does​

  • Registers as a payment method (Yui\Stripe\Plugin::getDetails()) so Stripe appears alongside any other payment method configured in the store, and creates a Stripe Checkout Session for the order total (line items, shipping, payment fee, and an inline fixed-amount coupon for the order discount) when the customer chooses it.
  • Redirects the customer to Stripe's hosted Checkout page; on return, resolves the Checkout Session by session_id and updates the order status via Sales After Payment Order Status.
  • Adds a public stripe/webhook endpoint that verifies the Stripe signature, deduplicates by Stripe event ID, and reconciles order status, subscriptions, and disputes for checkout.session.completed, payment_intent.succeeded/payment_intent.payment_failed, charge.refunded, charge.dispute.created/ charge.dispute.closed, invoice.paid/invoice.payment_failed, and customer.subscription.deleted. Every received event (handled or not) is logged to a local webhook log table.
  • Adds a Stripe → Dashboard page with revenue KPIs (today/week/month), transaction count and success rate, live Stripe balance (available/pending per currency), MRR and subscription counts when subscriptions exist, active dispute count, a 30-day revenue trend chart, a recent-transactions table, and a recent-webhook-events table. When subscriptions exist, also shows a subscription analytics section: monthly churn rate, dunning recovery rate, a 6-month MRR/new-subscriptions trend chart, a retention-by- cohort table, an MRR-by-plan breakdown, and a CSV export of all subscriptions -- see Developer API for the documented limitations of these figures.
  • Adds a Stripe → Payment History page listing Stripe orders (card brand/last 4/3D Secure once enriched from the Stripe API), with status, date-range filtering, and pagination.
  • Adds order-edit page components: a Pay by link button while an order is pending_payment, and once paid, a refund panel (full or partial, with a reason) plus a Manage in Stripe button that opens the Stripe Customer Portal for that order's customer.
  • Creates a Stripe refund (full or partial, with an optional duplicate/fraudulent/requested_by_customer reason and admin note) from the order edit page or the Developer API, and records it in yStore's shared refunds table.
  • Adds a Stripe → Subscriptions page listing subscriptions synced from Stripe (MRR, status, current period), a detail view per subscription, and cancel/pause/resume actions; subscriptions are kept current automatically via the invoice.paid, invoice.payment_failed, and customer.subscription.deleted webhook events, or manually via a console sync command.
  • Adds a Stripe → Disputes page listing chargebacks/disputes synced from charge.dispute.* webhook events, with a status filter, pagination, and an evidence submission form (customer/shipping/product/ receipt/refund-policy fields) that can save a draft or submit directly to Stripe.
  • Generates a Stripe Customer Portal session so a customer (or an admin, from the order edit page) can manage invoice history, payment methods, and -- if enabled -- cancel or update their subscription, without building a custom account UI.
  • Optionally offers Buy Now, Pay Later methods (Klarna, Afterpay/Clearpay) alongside card payments at checkout.
  • Exposes payment lookup, transaction listing, and an account summary as MCP tools for AI-agent-driven support/ops queries (see Developer API).
  • Activates the plugin license from Stripe → License.

Use Cases​

Admin / Craft CP​

  • Enter the Publishable key and Secret key from your Stripe Dashboard, then use Test Credentials on the Settings page to confirm they work before going live.
  • Set the Display Name and Select button name shown to the customer at checkout, and optional Instructions shown alongside the payment method.
  • Restrict when and where Stripe is offered with Visible From / Visible To dates and Available in countries.
  • Configure a webhook endpoint in the Stripe Dashboard pointing at stripe/webhook (shown on the Settings page) with the Webhook signing secret (whsec_...), so order status, subscriptions, and disputes stay in sync automatically instead of relying only on the customer's browser redirect.
  • Pick the Default currency and Default language used for the Stripe Checkout Session.
  • Turn on Enable BNPL and select which BNPL Methods (Klarna, Afterpay/Clearpay) to offer alongside card payments -- both must also be activated in the Stripe Dashboard.
  • Decide whether the Shipping Method and/or Payment Method are billed as their own Checkout line item.
  • Use Sandbox Mode together with the listed Stripe test card numbers to rehearse a full payment before taking the store live.
  • Review Stripe → Dashboard for revenue KPIs, live Stripe balance, MRR/subscription counts, active disputes, a revenue trend chart, and recent transactions/webhook activity at a glance. When subscriptions exist, also review churn rate, dunning recovery, retention by cohort, and MRR by plan, or download the full subscription list as CSV.
  • Use Stripe → Payment History to look up a Stripe order's card brand, last 4 digits, and 3D Secure result, filtering by status or date range.
  • From an order's edit page: share a Pay by link URL for an unpaid order, issue a full or partial refund with a reason, or open Manage in Stripe to hand the customer's Stripe Customer Portal session to them or inspect it yourself.
  • Manage recurring billing from Stripe → Subscriptions: see MRR and status at a glance, drill into a single subscription's period/plan/customer, and cancel, pause, or resume it.
  • Respond to chargebacks from Stripe → Disputes: filter by status, and submit evidence (or save a draft) directly against a dispute before its evidence due by deadline.
  • Activate the plugin license from Stripe → License.

Developer / Integrator​

  • Read the plugin's settings and services from Yui\Stripe\Plugin::getInstance() (or the Plugin::$plugin static) to build custom payment, refund, or reporting logic -- see Developer API.
  • Call stripe_check_payment, stripe_list_transactions, and stripe_summary MCP tools from an AI agent or automation to inspect payment status, list Stripe orders, or pull a live account summary (balance, KPIs, active disputes) -- see Developer API.
  • Use the yui-stripe/recurring/sync console command to backfill or reconcile subscriptions from Stripe into the local database, for example after enabling the plugin on a store with existing subscriptions.
  • Hook into the order-edit-extra-actions template hook output if you need to place custom UI near the plugin's own pay-by-link/refund/portal components -- see Developer API for exactly what is rendered and when.

Installation & Requirements​

Requirements​

  • Craft CMS 5 (craftcms/cms ^5.0.0)
  • yui/craft-core ^1, declared in require -- Settings extends yui\craftcore\models\BasePaymentSettingsModel at runtime
  • yui/craft-plugin ^2, declared in require as of 1.4.0 (previously a require-dev-only dependency)
  • stripe/stripe-php ^13.0 || ^16.0 (the official Stripe PHP SDK)
  • A Stripe account with API keys and, for automatic reconciliation, a configured webhook endpoint
  • Optional: yui/craft-mcp, for the MCP tools described above

Installation​

composer require yui/craft-stripe

After installing, enable the plugin in Settings → Plugins, then open Stripe → Settings and configure at minimum:

  1. Publishable key and Secret key on the Settings page, then Test Credentials to verify them.
  2. Default currency and Default language for the Checkout Session.
  3. A webhook endpoint in the Stripe Dashboard pointing at the stripe/webhook URL shown on the Settings page, with its Webhook signing secret entered back into the plugin.

See Settings for the full field reference.

Documentation​

  • Settings -- full settings reference, organized by section
  • Developer API -- services, webhook, MCP tools, console command, and data model
  • Release Notes -- notable changes between releases