KSA-ORACLE/WISE_QUICKSTART.md

# Wise Payment Integration - Quick Start Guide

## ✅ Installation Complete!

The Wise payment integration has been successfully implemented. Here's what you need to do to get it running.

## 🚀 Quick Setup (5 Minutes)

### Step 1: Add Environment Variables

Add these to your `.env` file:

```bash
# Wise Payment Configuration
WISE_API_URL=https://api.wise.com
WISE_API_TOKEN=your_token_here
WISE_PROFILE_ID=your_profile_id_here
WISE_WEBHOOK_SECRET=your_webhook_secret
WISE_RECIPIENT_NAME="Your Business Name"
WISE_RECIPIENT_EMAIL=payments@yourbusiness.com
```

### Step 2: Database is Ready ✅

The migration has already been run. Your `payments` table now has:
- `payment_provider` column
- `wise_payment_id` column
- `wise_session_id` column

### Step 3: Test It!

#### Option A: Test Without Wise Account (Development)

You can test the UI flow immediately:

1. Visit your card selection page
2. Select a paid option (6 or 18 cards)
3. You'll see two buttons: "Stripe" and "Wise"
4. Click "Wise" to test the flow

To simulate a successful payment during testing:

```bash
php artisan tinker
```

Then in Tinker:
```php
// Find the pending payment
$payment = App\Models\Payment::where('status', 'pending')->where('payment_provider', 'wise')->latest()->first();

// Mark it as succeeded
$payment->update(['status' => 'succeeded']);
```

Refresh the page and you'll be able to proceed to card drawing!

#### Option B: Test With Wise Sandbox

1. Create account at https://sandbox.transferwise.tech
2. Get your sandbox API token
3. Update `.env`:
   ```bash
   WISE_API_URL=https://sandbox.transferwise.tech
   ```

## 🎯 How It Works

### User Experience

1. **User visits card selection page**
   - Sees free option (1 card)
   - Sees paid options (6 & 18 cards) with dual payment buttons

2. **User clicks "Wise" button**
   - System creates payment record in database
   - User is redirected to payment page

3. **After payment**
   - Webhook updates payment status automatically
   - User can draw their cards once payment succeeds

### Behind the Scenes

```
cardSelection.vue
    ↓ (clicks Wise)
POST /create-wise-payment
    ↓
WiseController::createPaymentSession()
    ↓ (creates payment record)
Database: status = 'pending'
    ↓ (user pays)
POST /wise/webhook
    ↓
WiseController::handleWebhook()
    ↓
Database: status = 'succeeded'
    ↓
User can draw cards!
```

## 📁 What Was Changed

### Backend (PHP/Laravel)
- ✅ `app/Http/Controllers/WiseController.php` - New controller
- ✅ `app/Models/Payment.php` - Added Wise fields
- ✅ `routes/web.php` - Added Wise routes
- ✅ `bootstrap/app.php` - Added CSRF exception for webhooks
- ✅ Database migration - Already run

### Frontend (Vue/TypeScript)
- ✅ `resources/js/pages/cards/cardSelection.vue` - Dual payment buttons
- ✅ `resources/js/pages/payments/Pending.vue` - New pending page

### Configuration
- ✅ `.env.example` - Added Wise variables
- ✅ All code formatted with Pint & Prettier

## 🧪 Testing Checklist

- [ ] Environment variables added to `.env`
- [ ] Can see dual payment buttons on card selection
- [ ] Clicking "Wise" creates payment record
- [ ] Webhook endpoint is accessible (for production)
- [ ] Payment status updates correctly
- [ ] User can draw cards after payment succeeds

## 🔧 Production Setup

When you're ready to go live:

1. **Get Wise Business Account**
   - Sign up at https://wise.com
   - Complete business verification

2. **Get API Credentials**
   - Settings → API tokens
   - Create token with appropriate permissions
   - Note your Profile ID

3. **Configure Webhooks**
   - Settings → Webhooks
   - Add: `https://yourdomain.com/wise/webhook`
   - Subscribe to: `transfers#state-change` and `balance_credit`
   - Copy webhook secret

4. **Update `.env` for Production**
   ```bash
   WISE_API_URL=https://api.wise.com
   WISE_API_TOKEN=your_production_token
   WISE_PROFILE_ID=your_production_profile_id
   WISE_WEBHOOK_SECRET=your_production_webhook_secret
   ```

5. **Deploy & Test**
   - Deploy your changes
   - Test with a real small payment
   - Verify webhook is receiving events
   - Check logs: `storage/logs/laravel.log`

## 🆘 Troubleshooting

### "Payment not found" error
```bash
# Check if payment was created
php artisan tinker
>>> App\Models\Payment::latest()->first();
```

### Webhook not working
```bash
# Check logs
tail -f storage/logs/laravel.log

# Verify webhook endpoint is accessible
curl -X POST https://yourdomain.com/wise/webhook -v
```

### Payment stuck on "pending"
```bash
# Manually mark as succeeded for testing
php artisan tinker
>>> $payment = App\Models\Payment::where('client_session_id', 'YOUR-UUID')->first();
>>> $payment->update(['status' => 'succeeded']);
```

## 📚 Documentation

- **Full Setup Guide**: See `WISE_SETUP.md`
- **Implementation Details**: See `WISE_IMPLEMENTATION_SUMMARY.md`
- **Wise API Docs**: https://docs.wise.com/api-docs/

## 💡 Tips

1. **Start with sandbox** - Test everything before going live
2. **Monitor logs** - Check `storage/logs/laravel.log` regularly
3. **Test webhooks** - Use Wise's webhook testing tool
4. **Keep secrets safe** - Never commit `.env` to version control

## ✨ Features You Now Have

- ✅ Dual payment provider support (Stripe + Wise)
- ✅ Automatic webhook processing
- ✅ Payment validation before card drawing
- ✅ Pending payment page with auto-refresh
- ✅ Secure webhook signature verification
- ✅ User-friendly payment selection
- ✅ Full error handling

---

**Need Help?** Check the detailed guides:
- Setup: `WISE_SETUP.md`
- Implementation: `WISE_IMPLEMENTATION_SUMMARY.md`

**Ready to test?** Just add your Wise credentials to `.env` and visit your card selection page! 🎴