tractatus/docs/STRIPE_PORTAL_CONFIGURATION_STEPS.md

Stripe Customer Portal Configuration - Detailed Steps

Test Mode Configuration

Step 1: Navigate to Customer Portal Settings

1. Open your web browser
2. Go to: https://dashboard.stripe.com/test/settings/billing/portal
3. You should see the "Customer portal" page with a toggle for "Test mode" in the top-right corner
4. Ensure "Test mode" toggle is ON (blue)

---

Step 2: Activate the Customer Portal

You'll see one of two states:

If you see "Activate customer portal":

• Click the blue "Activate customer portal" button

If you see "Configure" or settings are already visible:

• Proceed to Step 3

---

Step 3: Configure Customer Information Section

Look for the "Customer information" section (usually at the top):

1. Find the checkbox labeled "Email address"

   • ✅ Check this box
   • This allows customers to update their email

2. Find the checkbox labeled "Payment methods"

   • ✅ Check this box
   • This allows customers to add/update payment methods

---

Step 4: Configure Subscription Settings

Scroll down to the "Subscriptions" section:

1. Find "Allow customers to cancel subscriptions"

   • Click the toggle or checkbox to enable it (should turn blue/green)

2. Under "Cancellation behavior", select:

   • Option: "Cancel at period end" (recommended)
   • This means subscriptions stay active until the end of the billing period

3. Find "Cancellation survey"

   • Click the toggle to enable it (should turn blue/green)

4. Click "Add question" or "Configure survey" button

---

Step 5: Configure Exit Survey Questions

Question 1 (Required):

1. Click "Add question"

2. Question type: Select "Multiple choice"

3. Question text: Type exactly:

   Why are you cancelling?
   

4. Required: Toggle ON (should be blue)

5. Answer options (click "Add option" for each):

   • Too expensive
   • No longer need it
   • Found an alternative
   • Not what I expected
   • Other

6. For the "Other" option:

   • ✅ Check "Allow text input" (this lets users explain further)

7. Click "Save" or "Add"

Question 2 (Optional):

1. Click "Add question" again
2. Question type: Select "Text"
3. Question text: Type exactly:

   How can we improve?
   

4. Required: Toggle OFF (leave unchecked)
5. Click "Save" or "Add"

---

Step 6: Configure Invoice History

Scroll to the "Invoice history" section:

1. Find "Show invoice history"
   • ✅ Check this box or toggle ON
   • This lets customers see past invoices and receipts

---

Step 7: Configure Business Information

Scroll to the "Business information" section:

1. Business name:

   • Type: Tractatus AI Safety Framework

2. Support email:

   • Type: support@agenticgovernance.digital

3. Privacy policy URL:

   • Type: https://agenticgovernance.digital/about/values.html

4. Terms of service URL:

   • Type: https://agenticgovernance.digital/about/values.html

---

Step 8: Review and Save

1. Scroll to the bottom of the page
2. Click the blue "Save changes" button
3. You should see a green success message: "Customer portal settings updated"

---

Live Mode Configuration

Once Test Mode is working, repeat the EXACT same steps for Live Mode:

Step 1: Switch to Live Mode

1. In the top-right corner of Stripe Dashboard, find the "Test mode" toggle
2. Click it to switch to Live mode (toggle should turn OFF/gray)
3. You may see a banner saying "You're now in live mode"

Step 2: Navigate to Live Customer Portal Settings

1. Go to: https://dashboard.stripe.com/settings/billing/portal
   • Note: This URL is slightly different (no /test/)

Step 3-8: Repeat Configuration

• Follow Steps 2-8 exactly as above
• Use the same settings, same text, same options
• CRITICAL: Don't skip any settings - Live and Test must match

---

Verification

Test Mode Verification:

1. Go to http://localhost:9000/koha.html
2. Scroll to "Manage Your Subscription" section
3. Enter an email with a test subscription
4. Click "Manage"
5. You should be redirected to Stripe Customer Portal
6. Verify you can see:
   • ✅ Subscription details
   • ✅ "Update payment method" option
   • ✅ "Cancel subscription" option
7. Click "Cancel subscription"
8. Verify the exit survey appears with your two questions

Live Mode Verification:

1. After deployment, go to https://agenticgovernance.digital/koha.html
2. Repeat the same test with your live subscription email
3. Test the full cancellation flow (you can cancel your $5 test subscription)

---

Troubleshooting

"No configuration provided" error:

• You haven't saved the portal configuration yet
• Go back to Step 8 and click "Save changes"
• Wait 30 seconds, then try again

Can't find "Customer portal" in settings:

• Make sure you're logged into the correct Stripe account
• Check that you have admin permissions
• Try this direct link: https://dashboard.stripe.com/test/settings/billing/portal

Changes not appearing:

• Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
• Check you're in the correct mode (Test vs Live)
• Stripe portal settings can take 1-2 minutes to propagate

Exit survey not showing:

• Verify "Cancellation survey" toggle is ON
• Check that at least one question is added
• Try creating a new test portal session

---

Screenshots Reference (What You Should See)

Customer Portal Settings Page:

• Top section: "Customer portal" heading with Test mode toggle
• Left sidebar: Settings, Billing, Customer portal
• Main area: Multiple configuration sections with toggles and inputs

After Activation:

• Customer information section (2 checkboxes)
• Subscriptions section (cancellation toggle + survey)
• Invoice history section (1 checkbox)
• Business information section (4 text inputs)
• Blue "Save changes" button at bottom

Exit Survey Configuration:

• Question list with drag handles
• Each question shows type (Multiple choice / Text)
• Edit/Delete buttons on each question
• "Add question" button at bottom

---

Time Required: 10-15 minutes total Last Updated: 2025-10-18