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:

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:

# 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

POST /create-wise-payment

Request:

{
  "count": 6  // or 18
}

Response:

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

Webhook Handler

POST /wise/webhook

Receives Wise webhook events and updates payment status.

Payment Validation

GET /wise/validate-payment?client_session_id={uuid}

Response:

{
  "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:

   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.