# 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
```bash
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:
```javascript
// 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)