KSA-ORACLE/WISE_PAYMENT_INTEGRATION.md

Wise Payment Integration - Complete Setup

This document describes the Wise payment integration that has been added to the oracle project, mirroring the implementation from the KSA-ORACLE project.

Overview

The Wise payment integration allows you to programmatically create international money transfers using the Wise API. This is a full API integration that enables:

• Creating recipient accounts
• Generating transfer quotes
• Initiating transfers
• Funding transfers from your Wise balance
• Tracking transfer status via webhooks

Backend Components

1. WisePaymentController (app/Http/Controllers/WisePaymentController.php)

Main controller that handles:

• createTransfer() - Creates a complete transfer flow (recipient → quote → transfer → funding)
• handleWebhook() - Processes Wise webhook notifications for transfer status updates
• checkTransferStatus() - Manually checks the status of a transfer

2. Payment Model (app/Models/Payment.php)

Updated with the following Wise-specific fields:

• wise_transfer_id - The Wise transfer ID
• wise_recipient_id - The recipient account ID in Wise
• wise_quote_id - The quote ID for the transfer
• target_currency - The currency the recipient will receive
• recipient_name - Name of the transfer recipient
• recipient_email - Email of the recipient
• error_message - Stores any error messages from failed transfers
• payment_provider - Set to 'wise' or 'stripe'
• wise_payment_id - Generic Wise payment identifier
• wise_session_id - Session tracking for Wise payments

3. Database Migrations

Two migrations have been created and applied:

Migration 1: 2025_10_14_130637_add_wise_fields_to_payments_table.php

• Adds: payment_provider, wise_payment_id, wise_session_id

Migration 2: 2025_10_14_145926_add_wise_transfer_fields_to_payments_table.php

• Adds: wise_transfer_id, wise_recipient_id, wise_quote_id, target_currency, recipient_name, recipient_email, error_message

4. API Routes (routes/api.php)

Route::post('/api/wise/transfer', [WisePaymentController::class, 'createTransfer']);
Route::post('/api/wise/webhook', [WisePaymentController::class, 'handleWebhook']);

Frontend Components

1. TypeScript Actions (resources/js/actions/App/Http/Controllers/WisePaymentController.ts)

Auto-generated route helpers for type-safe API calls:

• createTransfer.post() - Call the transfer creation endpoint
• handleWebhook.post() - Webhook endpoint (for backend use)

2. Checkout Page (resources/js/pages/Checkout.vue)

A complete Vue component with a form that includes:

• Amount input
• Source and target currency selection
• Recipient information (name, email, account number)
• Payment reason
• Error and success message handling
• Loading state management

Configuration

Environment Variables

Add these to your .env file (already documented in .env.example):

# Wise API Integration
WISE_API_KEY=your_wise_api_token_here
WISE_PROFILE_ID=your_wise_profile_id_here

# Wise Webhook Secret (optional, for webhook signature verification)
WISE_WEBHOOK_SECRET=your_webhook_secret_here

Getting Your Wise Credentials

1. API Key:

   • Go to https://wise.com/settings/api-tokens
   • Create a new token with appropriate permissions
   • Use either sandbox (test) or live API key

2. Profile ID:

   • Go to https://wise.com/settings/
   • Find your business or personal profile ID
   • This is usually a numeric ID

3. Webhook Secret (optional):

   • Go to https://wise.com/settings/webhooks
   • Create a webhook pointing to: https://yourdomain.com/api/wise/webhook
   • Copy the webhook secret for signature verification

Usage Example

Creating a Transfer from Frontend

import WisePaymentController from '@/actions/App/Http/Controllers/WisePaymentController'
import axios from 'axios'

const formData = {
    amount: 100.00,
    source_currency: 'USD',
    target_currency: 'EUR',
    recipient_name: 'John Doe',
    recipient_email: 'john@example.com',
    recipient_account_number: '1234567890',
    reason: 'Payment for services'
}

const response = await axios.post('/api/wise/transfer', formData)

if (response.data.success) {
    console.log('Transfer ID:', response.data.transfer_id)
    console.log('Payment ID:', response.data.payment_id)
}

Backend Transfer Creation Flow

1. Validates the request data
2. Creates a Payment record with status 'pending'
3. Creates a recipient account in Wise
4. Generates a quote for the transfer
5. Creates the transfer in Wise
6. Funds the transfer from your Wise balance
7. Updates the Payment record with transfer details and status 'processing'
8. Returns the transfer ID and payment ID

Webhook Handling

When Wise sends a webhook notification:

1. The handleWebhook() method receives the payload
2. Extracts the transfer ID from the webhook data
3. Finds the corresponding Payment record
4. Updates the payment status based on the transfer state
5. Logs the webhook for debugging

Database Schema

The payments table now includes these fields for Wise integration:

payment_provider VARCHAR(255) DEFAULT 'stripe'
wise_payment_id VARCHAR(255) NULLABLE
wise_session_id VARCHAR(255) NULLABLE
wise_transfer_id VARCHAR(255) NULLABLE
wise_recipient_id VARCHAR(255) NULLABLE
wise_quote_id VARCHAR(255) NULLABLE
target_currency VARCHAR(10) NULLABLE
recipient_name VARCHAR(255) NULLABLE
recipient_email VARCHAR(255) NULLABLE
error_message TEXT NULLABLE

Payment Status Flow

1. pending - Payment record created
2. processing - Transfer created and funded in Wise
3. succeeded / failed - Final status from Wise webhook

Dependencies

• GuzzleHTTP (guzzlehttp/guzzle: ^7.10) - Already installed
• Used for making HTTP requests to the Wise API

Testing

To test the integration:

1. Use Wise's sandbox environment first
2. Set WISE_API_KEY to your sandbox API key
3. Create test transfers to verify the flow
4. Monitor the Laravel logs for any API errors
5. Test webhook delivery using Wise's webhook testing tools

Security Considerations

1. Never commit your .env file with real API keys
2. Store WISE_API_KEY securely (use Laravel secrets in production)
3. Implement webhook signature verification using WISE_WEBHOOK_SECRET
4. Validate all user inputs before creating transfers
5. Use HTTPS in production for webhook endpoints

Additional Resources

• Wise API Documentation
• Wise Sandbox Environment
• Webhook Setup Guide

Notes

• The Wise API requires your account to have sufficient balance to fund transfers
• Some recipient types require additional fields (bank codes, IBAN, etc.)
• Transfer times vary by currency corridor
• API rate limits apply based on your Wise account tier

---

Integration Status: ✅ Complete Last Updated: October 14, 2025 Project: oracle (/media/creator/6226b912-8ba7-45dc-88a2-4b10d3dd1655/kandra/oracle)