ghostguild-org/HELCIM_TEST_INSTRUCTIONS.md

Helcim Integration Testing Guide

Setup Complete

The Helcim Recurring API integration has been set up with the following components:

1. Composables

• /app/composables/useHelcim.js - Server-side Helcim API interactions
• /app/composables/useHelcimPay.js - Client-side HelcimPay.js integration

2. Server API Endpoints

• /server/api/helcim/customer.post.js - Creates Helcim customer and member record
• /server/api/helcim/subscription.post.js - Creates subscription for paid tiers
• /server/api/helcim/verify-payment.post.js - Verifies payment token

3. Updated Pages

• /app/pages/join.vue - Multi-step signup flow with payment integration

4. Database Schema

• Updated /server/models/member.js with subscription fields

Testing Instructions

Prerequisites

1. Ensure your .env file has the test Helcim token:

   NUXT_PUBLIC_HELCIM_TOKEN=your_test_token_here
   

2. Ensure you have test payment plans created in Helcim dashboard matching these IDs:

   • supporter-monthly-5
   • member-monthly-15
   • advocate-monthly-30
   • champion-monthly-50

Test Flow

1. Start the Development Server

npm run dev

2. Test Free Tier Signup

1. Navigate to /join
2. Fill in name and email
3. Select any circle
4. Choose "$0 - I need support right now"
5. Click "Complete Registration"
6. Should go directly to confirmation without payment

3. Test Paid Tier Signup

1. Navigate to /join
2. Fill in test details:
   • Name: Test User
   • Email: test@example.com
3. Select any circle
4. Choose a paid contribution tier (e.g., "$15 - I can sustain the community")
5. Click "Continue to Payment"
6. On the payment step, use Helcim test card numbers:
   • Success: 4111 1111 1111 1111
   • Decline: 4000 0000 0000 0002
   • CVV: Any 3 digits
   • Expiry: Any future date
7. Click "Complete Payment"
8. Should see confirmation with member details

Test Card Numbers (Helcim Test Mode)

• Visa Success: 4111 1111 1111 1111
• Mastercard Success: 5500 0000 0000 0004
• Amex Success: 3400 0000 0000 009
• Decline: 4000 0000 0000 0002
• Insufficient Funds: 4000 0000 0000 0051

Debugging

Check API Responses

Open browser DevTools Network tab to monitor:

• /api/helcim/customer - Should return customer ID and token
• /api/helcim/verify-payment - Should return card details
• /api/helcim/subscription - Should return subscription ID

Common Issues

1. HelcimPay.js not loading

   • Check console for script loading errors
   • Verify token is correctly set in environment

2. Customer creation fails

   • Check API token permissions in Helcim dashboard
   • Verify MongoDB connection

3. Payment verification fails

   • Ensure you're using test card numbers
   • Check that Helcim account is in test mode

4. Subscription creation fails

   • Verify payment plan IDs exist in Helcim
   • Check that card token was successfully captured

Database Verification

Check MongoDB for created records:

// In MongoDB shell or client
db.members.findOne({ email: "test@example.com" })

Should see:

• helcimCustomerId populated
• helcimSubscriptionId for paid tiers
• status: "active" after successful payment
• paymentMethod: "card" for paid tiers

Next Steps

Once testing is successful:

1. Switch to production Helcim token
2. Create production payment plans in Helcim
3. Update plan IDs in /app/config/contributions.js if needed
4. Test with real payment card (small amount)
5. Set up webhook endpoints for subscription events (renewals, failures, cancellations)