Stripe Checkout Subscription

Stripe Checkout Subscription is a WordPress plugin that provides membership subscription functionality using Stripe Checkout. It stores subscription data (like invoice details, last payment date, etc.) in user meta, supports daily cron checks to maintain user roles, and comes with an intuitive admin interface for managing subscriptions.

Note: Currently I'm including the whole stripe PHP SDK folder in ./stripe but we should move to composer. This is a legacy from my existing application. It's a simple fix I just haven't got around to implementing it.

Table of Contents

1. Features
2. Requirements
3. Installation
4. Configuration
5. Usage
6. Admin Area
7. Shortcodes
8. Troubleshooting
9. Contributing
10. License

---

Features

• Stripe Checkout Integration: Redirects users to Stripe’s hosted checkout pages for streamlined subscription purchases.
• Webhook Handling: Uses WP REST endpoints to handle events like checkout.session.completed and invoice events (invoice.paid, invoice.payment_succeeded).
• Membership Role Assignment: Automatically assigns a configurable “premium” (or other) role upon successful payment.
• Daily Subscription Checks: Removes premium roles after a configurable time period (default 30 days) with no payment.
• Custom Admin Interface: Provides a dedicated admin menu for subscription management, plus a settings page to configure API keys and URLs.
• No Hard-Coding: All sensitive or site-specific data (Stripe keys, webhook secrets, role names, success/cancel URLs) is managed via a WordPress settings page.

---

Requirements

• WordPress 4.9+ (recommended 5.0+).
• PHP 7.2+ (recommended 7.4+ or 8+).
• A Stripe account and your secret key and webhook signing secret.
• Composer or manual installation of Stripe PHP library if modifying the plugin code (the plugin ships with stripe-php included in stripe/init.php).

---

Installation

1. Download or Clone

   • Download the plugin .zip file from your preferred source or clone the repo if you’re developing.

2. Upload to WordPress

   • Log into your WordPress admin area, go to Plugins → Add New, and upload the .zip file OR
   • Upload the plugin folder to your /wp-content/plugins/ directory manually.

3. Activate

   • In Plugins, find Stripe Checkout Subscription and click Activate.

4. Permalinks

   • If necessary, go to Settings → Permalinks and click Save Changes to ensure custom rewrite rules for checkout endpoints are flushed.

---

Configuration

After activating, navigate to Subscriptions → Settings in your WordPress admin menu. Here you can:

1. Stripe Secret Key

   • Your live or test secret key (e.g., sk_live_******** or sk_test_********).

2. Webhook Signing Secret

   • A signing secret generated by Stripe to validate webhook requests. When Debug Mode is disabled, signature verification is enforced.

3. Success/Cancel URLs

   • Set the return URLs for both your standard WordPress site flow and any external “app” flow.
   • If left blank, the plugin falls back to default URLs (e.g. home_url('/checkout-success?session_id={CHECKOUT_SESSION_ID}')).

4. Portal Return URL

   • The return URL for Stripe’s customer billing portal if using an external app environment.

5. Premium Role Name

   • Define the role to be assigned upon successful payments (defaults to premium_member).

6. Debug Mode

   • If enabled, the plugin will skip webhook signature verification (useful for local testing). Make sure to disable in production!

After saving your configuration, you’re ready to set up Stripe webhooks (see Usage below).

---

Usage

1. Stripe Webhook Setup

To ensure your site receives invoice updates and checkout session completions, add a webhook endpoint in your Stripe Dashboard:

• URL: https://yoursite.com/wp-json/stripe/v1/webhook
  (replace yoursite.com with your actual domain).
• Events: Typically checkout.session.completed, invoice.payment_succeeded, and invoice.paid.
• Signing Secret: Copy this from Stripe and place it in the plugin settings as Webhook Signing Secret.

2. Creating a Subscription Checkout Link

You can create links of the form:

https://yoursite.com/checkout/<USER_ID>/<PLAN>

where <PLAN> corresponds to a plan_slug in your code that maps to an actual Stripe Price ID. By default, the plugin’s plan lookup function uses 'monthly' => 'price_XXX', but you can modify or extend that in the plugin code if desired.

3. User Subscription Flow

1. A logged-in user visits /checkout/<user_id>/<plan>
2. The user is redirected to Stripe Checkout for payment.
3. On success, Stripe redirects back to the Success URL (configurable).
4. Webhook events update the user’s meta to record subscription details and assign the “premium” role.

---

Admin Area

You’ll find two new items in your Subscriptions menu:

1. Subscriptions (main page)

   • Lists all users (or filters by “Active,” “Expired,” “All”).
   • Shows each user’s subscription status, last payment date, and next renewal date (approx).
   • Actions:
     • Free Renewal: Manually extends a user’s subscription by updating last_payment_date.
     • Create Free Sub: Assigns the premium role and/or a free_trial role to the user, useful for testing or complimentary access.

2. Settings

   • The config page described above for your Stripe keys, webhook secret, URLs, role name, and debug mode.

---

Shortcodes

The plugin includes optional shortcodes:

1. [sps_checkout_link plan="monthly"]

   • Displays a button or link that sends the current logged-in user to /checkout/<user_id>/monthly.

2. [sps_manage_link]

   • Displays a link to /manage-subscription/<user_id> for the logged-in user to view their Stripe Billing Portal (if configured).

Feel free to customize the link/plan slug in your theme or plugin code.

---

Troubleshooting

1. Webhook Signature Verification Fails

   • Verify you copied the signing secret from Stripe exactly.
   • If Debug Mode is enabled, signature checks are skipped—disable for production.

2. No Premium Role Assigned

   • Make sure you have specified a valid role name in the Premium Role Name setting.
   • Check if your user meta fields (stripe_subscription_id, stripe_customer_id, etc.) are being updated.

3. Cron Not Working

   • WordPress crons rely on site traffic; ensure there is site traffic or consider using a real cron job (e.g., WP-CLI cron).
   • The plugin only removes premium role if no payment is recorded in the last 30 days (configurable in code).

4. Test Mode vs. Live Mode

   • Keep in mind you have separate secret keys, signing secrets, and webhooks for Test vs. Live in Stripe. Double-check you’re using the correct ones.

---

Contributing

• Pull Requests are welcome if you want to add new features, optimize code, or fix bugs.
• Issues can be opened for any problems you encounter or enhancements you suggest.
• Development: If you’re modifying the plugin extensively, ensure you test locally or on a staging environment. You might also run composer install to manage Stripe’s PHP library if updating dependencies.

---

Thank You

Thank you for using Stripe Checkout Subscription! We hope it simplifies your membership or subscription needs. If you have questions or feedback, feel free to open an issue or submit a pull request. Enjoy!