Inspiration
The true inspiration behind S.O.AI Mediator is the financial vulnerability of global freelancers and small businesses. In today's digital economy, millions negotiate business contracts casually inside messaging apps across borders, exposing themselves to payment delays or severe trust issues. Existing escrow platforms are tedious, locked behind complicated web forms, and extract heavy financial cuts. We built S.O.AI Mediator to close that trust gap, proving that conversational AI can act as a vigilant, independent, and instant financial protector — safeguarding the rights of both parties in their native languages through secure PayPal automations.
What it does
S.O.AI Mediator is an autonomous conversational fintech assistant that fully automates the freelance payment lifecycle through 4 secure phases:
- Multi-Lingual Agreement Detection: The agent monitors ongoing chats in any language (such as Arabic or English), extracts agreed terms, and structures them into precise financial milestone data.
- Automated PayPal Invoicing: It directly utilizes the PayPal Invoicing API to instantly generate and dispatch secure sandbox payment links to the client to lock the funds safely in escrow.
- Real-Time Webhook Monitoring: Through continuous Webhook triggers (INVOICING.INVOICE.PAID), the agent tracks payment statuses autonomously, instantly broadcasting a secure "Go-Ahead" production signal to the freelancer.
- AI Dispute Resolution (The Fair Compromise): If a client is unsatisfied with a delivery, an embedded AI Judge cross-references the original agreement with complaints to execute automated financial split compromises (e.g., 80% payout to freelancer and 20% refund to client via PayPal).
How we built it
The architecture of this project is fully mapped out using modern, scalable tools:
- Python & FastAPI: Designed as the core high-performance backend infrastructure to securely receive data and process live incoming PayPal webhook triggers.
- PayPal Invoicing API & Webhooks: Mapped to handle draft creations, secure billing triggers, and automated status checking loops.
- Streamlit: Drafted for an immersive, conversational front-end interface.
Ethical AI Use Acknowledgment: The system architecture, operational logic, and specific edge-case scenarios were fully designed and thought out by me. I leveraged generative AI assistants to code the base Python integrations, format the Streamlit layout, and refine the English documentation.
Core Architecture Blueprint (Python)
import os
import json
import paypalrestsdk
from fastapi import FastAPI, Request, HTTPException
from pydantic import BaseModel
from openai import OpenAI
app = FastAPI(title="S.O.AI Mediator: End-to-End AI Escrow System")
PAYPAL_CLIENT_ID = "YOUR_PAYPAL_CLIENT_ID"
PAYPAL_CLIENT_SECRET = "YOUR_PAYPAL_CLIENT_SECRET"
OPENAI_API_KEY = "YOUR_OPENAI_API_KEY"
paypalrestsdk.configure({
"mode": "sandbox",
"client_id": PAYPAL_CLIENT_ID,
"client_secret": PAYPAL_CLIENT_SECRET
})
ai_client = OpenAI(api_key=OPENAI_API_KEY)
PROJECTS_DB = {}
class ChatPayload(BaseModel):
client_email: str
freelancer_email: str
chat_history: str
@app.post("/ai/process-chat")
async def process_chat_and_create_escrow(payload: ChatPayload):
system_prompt = "You are an expert global AI Project Manager. Monitor chat agreements and extract milestones into strict English JSON format."
response = ai_client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "system", "content": system_prompt}, {"role": "user", "content": payload.chat_history}],
temperature=0.1
)
try:
ai_data = json.loads(response.choices[0].message.content.strip())
except:
raise HTTPException(status_code=500, detail="AI JSON parsing error")
if not ai_data.get("agreement_reached"):
return {"status": "Negotiation In Progress", "message": "S.O.AI Mediator Status: Monitoring conversation."}
return {"status": "Escrow Created", "message": "🤖 S.O.AI Mediator: Secure PayPal escrow payment link has been dispatched!"}