KSA-ORACLE/WISE_IMPLEMENTATION_SUMMARY.md

Wise Payment Integration - Implementation Summary

✅ What Has Been Implemented

1. Database Changes

• Migration created and run: add_wise_fields_to_payments_table
• New columns added to payments table:
  • payment_provider (default: 'stripe') - Identifies payment source
  • wise_payment_id - Stores Wise transfer ID
  • wise_session_id - Stores Wise session identifier

2. Backend Components

WiseController (app/Http/Controllers/WiseController.php)

• createPaymentSession() - Creates Wise payment and returns payment URL
• handleWebhook() - Processes Wise webhook events
• validatePayment() - Validates payment status manually
• Webhook signature verification for security

Routes (routes/web.php)

• POST /create-wise-payment - Create new Wise payment
• POST /wise/webhook - Receive Wise webhooks
• GET /wise/validate-payment - Check payment status
• Updated /success route to handle both Stripe and Wise

Payment Model (app/Models/Payment.php)

• Added Wise fields to $fillable array

3. Frontend Components

Card Selection (resources/js/pages/cards/cardSelection.vue)

• Split payment buttons: Users can choose "Stripe" or "Wise"
• redirectToWisePayment() function to handle Wise payment flow
• Visual distinction: Gold button for Stripe, Dark blue for Wise

Pending Page (resources/js/pages/payments/Pending.vue)

• New page for processing payments (especially Wise)
• Auto-polls payment status every 10 seconds
• Shows progress and provider information
• User-friendly interface with refresh option

4. Configuration

• .env.example updated with Wise configuration variables
• Comprehensive setup documentation in WISE_SETUP.md

🔄 Payment Flow

User selects paid option (6 or 18 cards)
    ↓
User clicks "Wise" button
    ↓
Frontend calls POST /create-wise-payment
    ↓
Backend creates Wise transfer & saves to DB (status: pending)
    ↓
User redirected to Wise payment page
    ↓
User completes payment on Wise
    ↓
Wise sends webhook to POST /wise/webhook
    ↓
Backend updates payment status to 'succeeded'
    ↓
User returns to /success page
    ↓
Success page validates payment
    ↓
If succeeded → User can draw cards
If pending → Show Pending page with auto-refresh

📋 Next Steps to Go Live

1. Set Up Wise Account

# Create Wise Business account at https://wise.com
# Navigate to Settings → API tokens
# Create API token and get Profile ID

2. Configure Environment Variables

Add to your .env file:

WISE_API_URL=https://api.wise.com
WISE_API_TOKEN=your_api_token_here
WISE_PROFILE_ID=your_profile_id
WISE_WEBHOOK_SECRET=your_webhook_secret
WISE_RECIPIENT_NAME="Your Business Name"
WISE_RECIPIENT_EMAIL=payments@yourbusiness.com

3. Set Up Webhooks

1. Go to Wise Settings → Webhooks
2. Create webhook: https://yourdomain.com/wise/webhook
3. Subscribe to: transfers#state-change and balance_credit
4. Copy webhook secret to .env

4. Testing

For testing without real Wise account:

# Use sandbox environment
WISE_API_URL=https://sandbox.transferwise.tech

# Or test by manually updating payment status:
php artisan tinker
>>> $payment = App\Models\Payment::where('client_session_id', 'YOUR-UUID')->first();
>>> $payment->update(['status' => 'succeeded']);

5. Make Webhook Accessible

Ensure your webhook endpoint is publicly accessible:

• Remove CSRF protection for /wise/webhook route (already handled in controller)
• Make sure your server accepts POST requests on this route
• Test with Wise's webhook testing tool

🎨 User Interface

Card Selection Screen

• Free Option: Single "Commencer" button
• Paid Options (6 & 18 cards):
  • Split into two buttons side-by-side
  • Left button (Gold): "Stripe"
  • Right button (Dark Blue): "Wise"

Payment Processing

• Stripe: Redirects to Stripe Checkout (existing flow)
• Wise: Redirects to Wise payment page
  • If payment pending: Shows Pending page with auto-refresh
  • If payment succeeded: Shows Success page

🔒 Security Features

1. Webhook Signature Verification: HMAC-SHA256 validation
2. Payment Status Checks: Before allowing card draws
3. One-time Use: Cards can only be drawn once per payment
4. Provider Tracking: Each payment tagged with provider

📊 Database Schema

payments table:
- id
- amount
- currency
- stripe_session_id (existing)
- client_session_id (existing)
- draw_count
- status (pending/succeeded/failed/refunded)
- cards
- appointment_date
- payment_provider (NEW: 'stripe' or 'wise')
- wise_payment_id (NEW)
- wise_session_id (NEW)
- created_at
- updated_at

🐛 Troubleshooting

Webhook Not Working

# Check Laravel logs
tail -f storage/logs/laravel.log

# Test webhook manually
curl -X POST https://yourdomain.com/wise/webhook \
  -H "Content-Type: application/json" \
  -H "X-Signature-SHA256: test" \
  -d '{"event_type":"test"}'

Payment Status Not Updating

# Check payment in database
php artisan tinker
>>> App\Models\Payment::where('payment_provider', 'wise')->latest()->get();

📚 Documentation

• Setup Guide: See WISE_SETUP.md for detailed configuration
• Wise API Docs: https://docs.wise.com/api-docs/
• Wise Sandbox: https://sandbox.transferwise.tech

🎯 Key Files Modified/Created

Backend

• ✅ app/Http/Controllers/WiseController.php (NEW)
• ✅ app/Models/Payment.php (MODIFIED)
• ✅ routes/web.php (MODIFIED)
• ✅ database/migrations/2025_10_14_130637_add_wise_fields_to_payments_table.php (NEW)

Frontend

• ✅ resources/js/pages/cards/cardSelection.vue (MODIFIED)
• ✅ resources/js/pages/payments/Pending.vue (NEW)

Configuration

• ✅ .env.example (MODIFIED)
• ✅ WISE_SETUP.md (NEW)
• ✅ WISE_IMPLEMENTATION_SUMMARY.md (NEW - this file)

✨ Features

• ✅ Dual payment provider support (Stripe + Wise)
• ✅ Webhook integration for automatic status updates
• ✅ Payment status validation before card drawing
• ✅ Pending payment page with auto-refresh
• ✅ Secure webhook signature verification
• ✅ User-friendly payment provider selection
• ✅ Comprehensive error handling
• ✅ Support for both sandbox and production environments

---

Status: ✅ Implementation Complete - Ready for Configuration & Testing