🔷

Square Subscription Setup

Complete Step-by-Step Guide for TuneShack / GrantPortal

Prepared by FMG Ecosystem · September 4, 2026

📋 What This Guide Covers

Access Square Dashboard

Create Subscription Plans

Generate Checkout Links

Set Up Webhooks

Add API Keys to App

Test Everything

⏱ Estimated time: 30–45 minutes

Phase 1: Access Square Dashboard

Go to Square Dashboard

Open your browser and go to: https://squareup.com/dashboard

💡

Make Sure You're in the Right Account

Check the top-left corner — it should show your business name (e.g. TuneShack / FMG).

💡

If you have multiple accounts, click the account name to switch.

Phase 2: Create a Subscription Plan

Click "Subscriptions" in the Left Menu

In the left sidebar, scroll down and click "Subscriptions". If you don't see it, go to: Items → Subscriptions.

💡

You may need to enable Subscriptions from your Square account first (it's free).

Click "Create a Plan"

On the Subscriptions page, click the green "Create a plan" button at the top right.

Fill In the Plan Details

Plan Name: e.g. "GrantPortal Monthly"
Price: $9.99
Billing Cycle: Monthly
Trial Period: Optional (leave blank if none)

💡

Repeat this step to create your Annual ($79/yr) and Lifetime ($199) plans.

Save the Plan

Click "Save" or "Create Plan". You'll see it listed on the Subscriptions page.

Phase 3: Get Your Checkout Links

Go to Online Checkout Links

In the left menu: Online → Payment Links (or go to squareup.com/dashboard/online-checkout)

Click "Create a Link"

Click the "Create a link" button. Choose "Subscription" as the payment type.

Select Your Subscription Plan

Choose the plan you just created (e.g. GrantPortal Monthly). Set your redirect URL to:
https://tuneshack.ca/GrantPortal?subscribed=1

💡

This sends the user back to your app after they pay, with their email auto-activating.

Copy the Checkout Link

Square will generate a link like:
https://square.link/u/XXXXXXXX

Copy this link — you'll paste it into your app settings.

💡

Create a separate link for each plan: Monthly, Annual, Lifetime.

Phase 4: Set Up Webhooks (Automatic Notifications)

Go to Developer Portal

Open a new tab and go to: https://developer.squareup.com/apps
Sign in with the same Square account.

Open Your App

Click on your app (or create one if you haven't yet — name it "TuneShack GrantPortal").

Go to Webhooks Tab

Inside your app settings, click the "Webhooks" tab. Click "Add Webhook".

Enter the Webhook URL

Paste this URL into the "Notification URL" field:
https://tuneshack-connect-hub.base44.app/api/fn/squareMembershipWebhook

💡

This is the URL that Square will ping every time someone subscribes or cancels.

Select Events to Listen For

Check these events:
✅ subscription.created
✅ subscription.updated
✅ invoice.payment_made
✅ invoice.payment_failed

💡

These cover new sign-ups, renewals, and cancellations.

Save Webhook & Copy the Signature Key

Click Save. Square will show you a "Signature Key" — copy it immediately.

💡

Paste this key into your app's Settings → Secrets → SQUARE_WEBHOOK_SIGNATURE_KEY

Phase 5: Add Your API Keys to the App

Get Your Square API Keys

In the developer portal, go to your app → Credentials tab.
Copy these values:
• Application ID
• Access Token (Production)
• Location ID (from Locations tab)

💡

Make sure you are using PRODUCTION credentials, not Sandbox.

Add Secrets to Your Base44 App

In your Base44 dashboard:
1. Click Settings (gear icon)
2. Click Environment Variables / Secrets
3. Add:
   SQUARE_ACCESS_TOKEN = (your access token)
   SQUARE_APPLICATION_ID = (your app ID)
   SQUARE_LOCATION_ID = (your location ID)
   SQUARE_WEBHOOK_SIGNATURE_KEY = (from Step 16)

💡

All 4 keys must be set for subscriptions to work end-to-end.

Phase 6: Test Everything

Test a Checkout

Go to your GrantPortal page → Click Subscribe → Use a real card (Square charges real money in production).
Or use Sandbox mode first: switch your API keys to Sandbox credentials and test with card number: 4111 1111 1111 1111

Verify the Webhook Fired

After payment, check your Base44 app:
• Go to Code → Functions → squareMembershipWebhook
• Check the logs — you should see the subscription event received.

Check the Subscriber Was Created

In your Base44 app:
• Go to Data → GrantPortalSubscriber
• You should see a new record with status: active

💡

If the record isn't there, check webhook logs for errors.

🚨 Common Problems & Fixes

❌ Subscriber not appearing in database

✅ Fix: Check webhook URL is correct and SQUARE_WEBHOOK_SIGNATURE_KEY is set in secrets.

❌ Checkout link not working

✅ Fix: Make sure you copied the Production link, not the Sandbox link.

❌ Webhook showing errors

✅ Fix: Go to Developer Portal → Your App → Webhooks → View failed deliveries for details.

❌ "Invalid signature" error in logs

✅ Fix: Re-copy the Signature Key from Square and re-paste it into Base44 secrets. They must match exactly.

❌ User gets redirected but access code not sent

✅ Fix: Check that RESEND_API_KEY is set and the grantPortalSubscribe function is working (test it in Base44 → Code → Functions).

⚡ Quick Reference — Important URLs

Square Dashboard:https://squareup.com/dashboard

Square Developer Portal:https://developer.squareup.com/apps

Webhook URL (paste into Square):https://tuneshack-connect-hub.base44.app/api/fn/squareMembershipWebhook

GrantPortal Redirect After Payment:https://tuneshack.ca/GrantPortal?subscribed=1

✅ Secrets Checklist — All Must Be Set in Base44

SQUARE_ACCESS_TOKEN— Your Square Production Access Token

SQUARE_APPLICATION_ID— Your Square App ID (starts with "sq0idp-")

SQUARE_LOCATION_ID— Your Square Location ID

SQUARE_WEBHOOK_SIGNATURE_KEY— From Square Developer → Webhooks → Signature Key

RESEND_API_KEY— For sending access code emails after payment

TuneShack / FMG Ecosystem · GrantPortal Setup Guide

Need help? Contact: fmg6ix@gmail.com