GB Stripe Payments Plugin – Complete Documentation

Add-on for Gym Builder

1. Overview

GB Stripe Payments is a premium add-on for Gym Builder that enables secure subscription and one-time payments using Stripe. It supports recurring billing, pricing plan synchronization, class slot booking with atomic locking, membership auto-activation, and a full student subscription dashboard.

This documentation provides a complete setup and usage guide from installation to frontend flow.

2. Prerequisites

Before installation, ensure:

✅ Gym Builder plugin is installed and activated

✅ A Stripe account is created at https://dashboard.stripe.com

✅ WordPress cron is enabled (for subscription maintenance)

Important Compatibility Notice

If Class Booking with WooCommerce & Offline Payment Addon is active, GB Stripe Payments will not function. Only one payment handler should be active at a time.

3. Plugin Activation

Activate the Plugin

Navigate to:

WordPress Admin → Plugins → Installed Plugins → GB Stripe Payments → Activate

What Happens on Activation

The plugin automatically:

  • Creates two database tables:
    • wp_gb_stripe_subscriptions
    • wp_gb_stripe_payment_logs
  • Stores default configuration options
  • Schedules a daily cron job for subscription cleanup

If Gym Builder is not active, an admin notice appears:

“GB Stripe Payments requires Gym Builder plugin to be active.”

4. Stripe Configuration

Navigate to:

WordPress Admin → Gym Builder → Stripe Payments

This opens the settings interface (React-based admin panel).

Tab 1: API Keys

Configure Stripe API credentials.

  1. Stripe Mode
    • Test → Development
    • Live → Production
  2. Test Publishable Key
    • Stripe Dashboard → Developers → API Keys
    • Format: pk_test_...
  3. Test Secret Key
    • Same location
    • Format: sk_test_...
  4. Webhook Secret
    • Will be generated in Step 5

Click Save Settings.

Tab 2: General Settings (#general)

  1. Auto-activate membership on payment
    • Recommended: ON
    • Automatically activates Gym Builder membership after successful payment
  2. Success Page
    • Page users land on after successful checkout
  3. Cancel Page
    • Page users see after canceling checkout
  4. Button Text
    • Customize Subscribe button text
    • Default: “Subscribe Now”

Click Save Settings.

Tab 3: Sync Packages (#sync)

Used after pricing plans are created (see Step 6).

5. Stripe Webhook Setup

Stripe must notify your website when payments succeed or fail.

Webhook URL

https://your-domain.com/wp-json/gb-stripe/v1/webhook

For local development (example):

http://gym-builder.test/wp-json/gb-stripe/v1/webhook

Configure in Stripe

  1. Go to Stripe Dashboard → Developers → Webhooks
  2. Click Add endpoint
  3. Paste your webhook URL
  4. Select these events:
    • checkout.session.completed
    • invoice.payment_succeeded
    • invoice.payment_failed
    • customer.subscription.updated
    • customer.subscription.deleted
  5. Click Add endpoint
  6. Copy the Signing Secret (whsec_...)
  7. Paste it in:
    WordPress → Gym Builder → Stripe Payments → API Keys → Webhook Secret
  8. Save Settings

Local Testing (Stripe CLI)

Install Stripe CLI and run:

stripe listen --forward-to http://gym-builder.test/wp-json/gb-stripe/v1/webhook

6. Create Pricing Plans

Navigate to:

WordPress Admin → Gym Builder → Pricing Plans → Add New

Configure Basic Plan

  1. Set Title (e.g., “Premium Monthly”)
  2. Set base price and duration
  3. Assign Pricing Plan Category

Enable Stripe Billing

In the Stripe Billing Settings metabox:

  1. Enable Stripe → Yes
  2. Select Billing Intervals:
    • Monthly
    • Bi-Monthly
    • Quarterly
    • Yearly
    • One-Time
  3. Enter prices per interval
  4. Publish the plan

7. Sync Packages to Stripe

Navigate to:

Gym Builder → Stripe Payments → Sync Packages

Click:

Sync All Packages

This process:

  • Creates a Stripe Product for each enabled plan
  • Creates Stripe Prices per interval
  • Stores Stripe Product & Price IDs in post meta
  • Automatically creates new Stripe prices if pricing changes (Stripe prices are immutable)

You’ll see:

“Synced X of Y packages.”

8. Class Setup (Optional)

If your gym offers scheduled classes with limited slots:

Navigate to:

Gym Builder → Classes → Add/Edit Class

Configure:

  • Schedule (day & time)
  • Capacity (total_slot)
  • Linked pricing plans

Slot Protection

When users subscribe:

  • Slot availability is checked via AJAX
  • Booking is atomic using database locks
  • Prevents race conditions and overbooking

9. Frontend User Flow

Step 1: User Views Pricing Plans

Stripe-enabled packages show a Subscribe Now button.

Step 2: Subscription Modal

User selects:

  • Billing interval
  • Class
  • Day
  • Time slot (with available slot count)

Step 3: Checkout Initialization

When clicking Subscribe:

  1. Validates slot availability
  2. Creates pending subscription in gb_stripe_subscriptions
  3. Creates Stripe Checkout Session
  4. Redirects to Stripe-hosted checkout

Step 4: Stripe Checkout Page

User enters card details securely via Stripe.

Example test card:

4242 4242 4242 4242
Exp: 12/27
CVC: 123

Step 5: Webhook Processing

After successful payment:

Stripe sends checkout.session.completed.

The plugin:

  1. Verifies Stripe signature
  2. Books class slot (DB lock safe)
  3. Updates subscription to active
  4. Updates gym_builder_members:
    • membership_status = 1
    • Sets start & end dates
    • Stores package & class details
  5. Assigns gym_builder_student role
  6. Sends confirmation email
  7. Redirects to Success Page

10. Success Page

Displays:

  • Subscription confirmation
  • Package name
  • Class schedule
  • Dashboard link

11. Student Dashboard Integration

Accessible via:

Gym Builder → Student Dashboard
(or via shortcode placement)

The plugin adds a My Subscriptions section showing:

  • Package Name
  • Status (Active / Canceled / Past Due)
  • Billing interval
  • Next billing date
  • Class & schedule
  • Auto-renew toggle

12. User Subscription Actions

Users can:

1. Toggle Auto-Renew

  • Cancels at period end in Stripe

2. Cancel Subscription

  • Immediate cancellation (one-time)
  • End-of-period cancellation (recurring)

3. Resubscribe

  • Creates a new checkout session

4. Update Payment Method

  • Opens Stripe Billing Portal
  • Used for past_due subscriptions

13. Database Structure

Table: wp_gb_stripe_subscriptions

Stores:

  • User ID
  • Stripe Subscription ID
  • Package ID
  • Class schedule info
  • Status
  • Billing interval
  • Period start & end

Table: wp_gb_stripe_payment_logs

Stores:

  • Stripe event ID
  • Event type
  • Payload
  • Processing result

14. Security & Reliability

  • Stripe signature verification
  • Immutable price handling
  • Atomic class slot booking
  • Race condition prevention
  • Webhook-based source of truth
  • Cron-based cleanup

15. Recommended Production Checklist

Before going live:

  • Switch Stripe Mode → Live
  • Add Live API Keys
  • Create Live Webhook endpoint
  • Test with small real transaction
  • Confirm emails are working
  • Ensure SSL (HTTPS) is enabled

16. Support & Troubleshooting

Payment Not Activating?

  • Check Webhook Secret
  • Confirm webhook events are received in Stripe
  • Check wp_gb_stripe_payment_logs

Slot Overbooking?

  • Confirm class total_slot is set
  • Ensure webhook is firing correctly

Conclusion

GB Stripe Payments transforms Gym Builder into a fully automated subscription system with:

  • Secure Stripe checkout
  • Recurring billing
  • Membership automation
  • Class slot management
  • Student dashboard controls

With proper webhook configuration and package sync, your gym website can run a complete subscription-based business model securely and efficiently.