KSA-ORACLE/WISE_SIMPLE_SETUP.md

Wise Payment Integration - Simple Setup (Payment Links)

🎯 Overview

This is a simplified implementation using Wise payment links that your client has already provided. Users click a button, get redirected to Wise to pay, and then we verify the payment afterward.

✅ What's Already Done

All the code is ready! You just need to configure the payment links.

🚀 Quick Setup (2 Minutes)

Step 1: Add Payment Links to .env

Your client provided you with a link like: https://wise.com/pay/r/W2k1NqQySdc9HW8

Add these to your .env file:

# Wise Payment Links (one for each product)
WISE_PAYMENT_LINK_6_CARDS=https://wise.com/pay/r/W2k1NqQySdc9HW8
WISE_PAYMENT_LINK_18_CARDS=https://wise.com/pay/r/YOUR_OTHER_LINK_HERE

# Webhook secret (optional for now, needed later for automatic verification)
WISE_WEBHOOK_SECRET=

Step 2: Test It!

That's it! You can now test:

1. Visit your card selection page
2. Select a paid option (6 or 18 cards)
3. Click the "Wise" button
4. You'll be redirected to the Wise payment page

🔄 How It Works

┌─────────────────────────────────────────────────────────────┐
│  1. User clicks "Wise" button on card selection             │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│  2. Backend creates payment record in database              │
│     - status: 'pending'                                      │
│     - payment_provider: 'wise'                               │
│     - Saves client_session_id (UUID)                         │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│  3. User redirected to Wise payment link                    │
│     Example: https://wise.com/pay/r/W2k1NqQySdc9HW8         │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│  4. User completes payment on Wise website                  │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│  5. User manually returns to your site                      │
│     Goes to: /wise/verify                                    │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│  6. System checks payment status in database                │
│     - If succeeded → Redirect to success page               │
│     - If still pending → Show "check again" button          │
└─────────────────────────────────────────────────────────────┘

📱 User Experience

Step 1: Card Selection

User sees three options with dual payment buttons:

• Free option: Single "Commencer" button
• 6 cards (9.99€): [Stripe] [Wise] buttons
• 18 cards (15.90€): [Stripe] [Wise] buttons

Step 2: Click Wise Button

• Payment record created in database
• User redirected to: https://wise.com/pay/r/W2k1NqQySdc9HW8

Step 3: Payment on Wise

• User completes payment on Wise's secure website
• Wise processes the payment

Step 4: Return & Verification

Two options:

Option A: User returns via custom link

• User clicks "Back to site" or similar
• Goes to: /wise/verify
• System checks payment status
• If paid → Success! Access granted to cards

Option B: Webhook (automatic - recommended)

• Wise sends notification to your server
• Payment status updated automatically
• User can verify anytime

🔧 For Production: Set Up Webhooks

To make verification automatic (so users don't have to manually check):

1. Set Up Webhook URL

In your Wise business account:

1. Go to Settings → Webhooks
2. Add new webhook: https://yourdomain.com/wise/webhook
3. Subscribe to these events:
   • transfers#state-change
   • balance_credit
4. Copy the webhook secret

2. Add Webhook Secret

Add to your .env:

WISE_WEBHOOK_SECRET=your_webhook_secret_here

Now when users pay, the status updates automatically!

🧪 Testing Workflow

Manual Testing (Without Real Payment)

1. Create test payment:

   # Click Wise button on card selection
   # This creates a pending payment in database
   

2. Simulate successful payment:

   php artisan tinker
   

   Then in Tinker:

   // Get the latest Wise payment
   $payment = App\Models\Payment::where('payment_provider', 'wise')
                                 ->where('status', 'pending')
                                 ->latest()
                                 ->first();
   
   // Mark it as succeeded
   $payment->update(['status' => 'succeeded']);
   
   // Exit
   exit
   

3. Verify:

   • Go to /wise/verify page
   • Should show "Payment succeeded!"
   • Should redirect to success page
   • User can now draw cards

Testing With Real Payment

1. Click "Wise" button
2. Complete payment on Wise (use smallest amount for test)
3. After payment, go to /wise/verify
4. System should detect payment succeeded

📂 Key Files

Backend

• app/Http/Controllers/WiseController.php - Handles payment creation and verification
• routes/web.php - Routes for payment and webhook
• .env - Configuration (payment links and webhook secret)

Frontend

• resources/js/pages/cards/cardSelection.vue - Payment selection with dual buttons
• resources/js/pages/wise/VerifyPayment.vue - Verification page after payment
• resources/js/pages/payments/Success.vue - Success page (access to cards)

🔐 Security

• ✅ Payment records stored before redirect
• ✅ Status verified before allowing card access
• ✅ Webhook signature verification (when configured)
• ✅ Client session ID prevents unauthorized access

💡 Important Notes

Return URL Configuration

After users complete payment on Wise, they need to return to your site. Options:

1. Manual Return: User clicks browser back or a link
2. Wise Return URL: Ask your client if they can add a return URL to the payment link settings
   • Ideal return URL: https://yourdomain.com/wise/verify

Multiple Payment Links

You need separate payment links for:

• 6 cards (9.99€)
• 18 cards (15.90€)

Ask your client to create both links in their Wise account.

🆘 Troubleshooting

"Payment link not configured"

• Check .env has WISE_PAYMENT_LINK_6_CARDS and WISE_PAYMENT_LINK_18_CARDS
• Make sure links are valid Wise payment URLs

Payment status stuck on "pending"

# Check payment was created
php artisan tinker
>>> App\Models\Payment::where('payment_provider', 'wise')->latest()->first();

# Manually mark as succeeded for testing
>>> $payment = App\Models\Payment::where('client_session_id', 'YOUR-UUID')->first();
>>> $payment->update(['status' => 'succeeded']);

Webhook not working

• Make sure webhook URL is publicly accessible
• Verify WISE_WEBHOOK_SECRET in .env
• Check logs: tail -f storage/logs/laravel.log

✨ Next Steps

1. ✅ Done: Code is implemented
2. 📝 Now: Add payment links to .env
3. 🧪 Test: Click Wise button and verify redirect
4. 🔗 Production: Set up Wise webhooks
5. 🎉 Launch: Ready for users!

---

Need the other payment link? Ask your client to create a second Wise payment link for the 18-card option (15.90€) and add it to .env.

Questions? Check the logs: storage/logs/laravel.log