KSA-ORACLE/WISE_SETUP.md

# Wise Payment Integration Setup Guide

This guide explains how to set up and use the Wise payment integration for your tarot card reading application.

## Overview

The Wise integration allows users to pay for card readings using Wise (formerly TransferWise) alongside the existing Stripe integration. When a user selects a paid option, they can now choose between Stripe and Wise as their payment provider.

## Flow

1. **Card Selection** - User selects a paid reading option (6 or 18 cards)
2. **Payment Provider Choice** - User clicks either "Stripe" or "Wise" button
3. **Payment Creation** - Backend creates a payment session with Wise API
4. **Payment Redirect** - User is redirected to Wise payment page
5. **Webhook Verification** - Wise sends webhook to confirm payment
6. **Access to Tirage** - Once payment is verified (status = 'succeeded'), user can draw cards

## Database Changes

### Migration

Run the migration to add Wise fields to the payments table:

```bash path=null start=null
php artisan migrate
```

This adds:
- `payment_provider` - Identifies whether payment is 'stripe' or 'wise'
- `wise_payment_id` - Wise transfer ID
- `wise_session_id` - Wise session identifier

## Configuration

### 1. Set Up Wise Account

1. Create a Wise Business account at https://wise.com
2. Navigate to Settings → API tokens
3. Create a new API token with appropriate permissions
4. Get your Profile ID from the API settings

### 2. Environment Variables

Add these to your `.env` file:

```bash path=null start=null
# Wise Payment Configuration
WISE_API_URL=https://api.wise.com  # Use https://sandbox.transferwise.tech for testing
WISE_API_TOKEN=your_wise_api_token_here
WISE_PROFILE_ID=your_profile_id_here
WISE_WEBHOOK_SECRET=your_webhook_secret_here
WISE_RECIPIENT_NAME="Your Business Name"
WISE_RECIPIENT_EMAIL=payments@yourbusiness.com
```

**For Testing:**
- Use `WISE_API_URL=https://sandbox.transferwise.tech` for sandbox environment
- Create a sandbox account at https://sandbox.transferwise.tech

### 3. Configure Webhooks

In your Wise account:

1. Go to Settings → Webhooks
2. Create a new webhook
3. Set the URL to: `https://yourdomain.com/wise/webhook`
4. Subscribe to these events:
   - `transfers#state-change` - For transfer status updates
   - `balance_credit` - For balance credit notifications
5. Copy the webhook secret and add it to your `.env` as `WISE_WEBHOOK_SECRET`

## API Endpoints

### Payment Creation
```bash path=null start=null
POST /create-wise-payment
```

**Request:**
```json
{
  "count": 6  // or 18
}
```

**Response:**
```json
{
  "success": true,
  "paymentUrl": "https://api.wise.com/pay/12345",
  "transferId": "12345",
  "clientSessionId": "uuid-here"
}
```

### Webhook Handler
```bash path=null start=null
POST /wise/webhook
```

Receives Wise webhook events and updates payment status.

### Payment Validation
```bash path=null start=null
GET /wise/validate-payment?client_session_id={uuid}
```

**Response:**
```json
{
  "success": true,
  "drawCount": 6
}
```

## Frontend Changes

The `cardSelection.vue` component now has dual payment buttons:

- **Stripe Button** (Gold) - Uses existing Stripe flow
- **Wise Button** (Dark Blue) - Uses new Wise flow

Both buttons appear for the paid options (6 cards and 18 cards).

## How It Works

### Payment Flow

1. User clicks "Wise" button on card selection
2. `redirectToWisePayment()` function calls `/create-wise-payment`
3. Backend:
   - Creates Wise quote for the amount
   - Creates recipient account
   - Creates transfer with customer transaction ID
   - Stores payment record with `status='pending'` and `payment_provider='wise'`
4. User is redirected to Wise payment page
5. User completes payment on Wise
6. Wise sends webhook to `/wise/webhook`
7. Webhook handler updates payment status to `'succeeded'`
8. User returns to success page
9. Success page validates payment status
10. If payment succeeded, user can proceed to draw cards

### Webhook Handling

The `WiseController::handleWebhook()` method processes:

- **transfer_state_change**: Updates payment status based on transfer state
  - `outgoing_payment_sent` → `processing`
  - `funds_refunded` → `refunded`
  - `bounced_back` → `failed`

- **balance_credit**: Marks payment as `succeeded` when funds are received

### Payment Verification

Before allowing card drawing, the system checks:

1. Payment exists in database
2. `client_session_id` matches
3. `status` is `'succeeded'`
4. `payment_provider` is `'wise'`

This happens in the `/success` route and ensures users can only draw cards after payment is confirmed.

## Important Notes

### Wise API Differences from Stripe

Unlike Stripe Checkout, Wise doesn't have a hosted payment page URL that you redirect to directly. The implementation provided creates the transfer but you'll need to implement one of these options:

**Option 1: Manual Payment Instructions**
- Show users the transfer details and ask them to pay manually
- Check status via webhooks or polling

**Option 2: Wise Payment Links** (Recommended)
- Use Wise's payment link feature (if available in your region)
- Contact Wise support to enable this feature

**Option 3: Custom Integration**
- Build a custom payment form that collects payment method details
- Use Wise API to process the payment

### Testing

For testing, you can:

1. Use Wise sandbox environment
2. Manually update payment status in database:
   ```sql
   UPDATE payments SET status='succeeded' WHERE client_session_id='your-uuid';
   ```
3. Test webhook with Wise's webhook testing tool

### Security

- **Webhook signatures** are verified using HMAC-SHA256
- **Payment validation** checks status before allowing card draws
- **One-time use** - Cards can only be drawn once per payment

## Troubleshooting

### Webhook not receiving events
1. Check your webhook URL is publicly accessible
2. Verify `WISE_WEBHOOK_SECRET` matches Wise dashboard
3. Check Laravel logs: `storage/logs/laravel.log`

### Payment not marking as succeeded
1. Check webhook is being received (check logs)
2. Verify payment record exists with correct `wise_payment_id`
3. Manually check transfer status via Wise dashboard

### User can't draw cards after payment
1. Verify payment status is `'succeeded'` in database
2. Check `client_session_id` is being passed correctly in URL
3. Verify payment provider is set to `'wise'`

## Next Steps

1. **Run the migration**: `php artisan migrate`
2. **Configure .env**: Add all Wise environment variables
3. **Set up webhooks**: Configure in Wise dashboard
4. **Test in sandbox**: Use Wise sandbox for testing
5. **Go live**: Switch to production API URL and credentials

## Support

For Wise API documentation, visit:
- API Docs: https://docs.wise.com/api-docs/
- Sandbox: https://sandbox.transferwise.tech
- Support: https://wise.com/help/

For issues with this integration, check the Laravel logs and Wise dashboard for detailed error messages.