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:

# 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:

php artisan tinker

Then in Tinker:

// 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:

   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

   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

# Check if payment was created
php artisan tinker
>>> App\Models\Payment::latest()->first();

Webhook not working

# 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"

# 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! 🎴