YeboSafe

Secure payments. Protected transactions.

Status: 🔄 Building

---

What is YeboSafe?

YeboSafe is Yebo's payment infrastructure. It provides:

• User wallets
• Mobile money integration
• Escrow for transactions
• Cross-border transfers

Every Yebo transaction flows through YeboSafe.

---

Core Features

Wallet

Every user has a wallet:

• Receive payments from sales
• Get paid for jobs
• Hold escrow funds
• Withdraw to mobile money

Mobile Money

Integrated with:

• M-Pesa (Kenya, Tanzania)
• MTN Mobile Money (Ghana, Uganda)
• Airtel Money (multiple)
• More coming

Escrow

Protects both buyers and sellers:

Buyer pays → YeboSafe holds → Seller ships → Buyer confirms → Seller receives

---

How It Works

Deposit (Mobile Money → Wallet)

User: "Add 1000 to my wallet"

Agent:
→ Initiates M-Pesa STK Push
→ User sees prompt on phone
→ User enters PIN
→ "KES 1,000 added to your wallet.
   Balance: KES 2,500"

Withdraw (Wallet → Mobile Money)

User: "Withdraw 500 to M-Pesa"

Agent:
→ "Withdrawing KES 500 to +254712345678
   Fee: KES 10
   You'll receive: KES 490
   Confirm?"

User: "Yes"

Agent:
→ "Done! Check your M-Pesa."

Escrow (Commerce)

Buyer purchases item for KES 3,000
        │
        ▼
YeboSafe holds KES 3,000 in escrow
        │
        ▼
Seller ships item
        │
        ▼
Buyer confirms receipt
        │
        ▼
YeboSafe releases KES 2,850 to seller (5% fee)

---

Escrow States

CREATED      Order placed, awaiting payment
    │
    ▼
FUNDED       Buyer paid, funds held
    │
    ▼
SHIPPED      Seller marked as shipped
    │
    ├──► DELIVERED → RELEASED (success)
    │
    └──► DISPUTED → REFUNDED (failure)

---

API (Internal)

Create Wallet

POST /wallets
{
  "userId": "uuid",
  "currency": "KES"
}

Deposit

POST /deposits
{
  "walletId": "uuid",
  "amount": 1000,
  "provider": "mpesa",
  "phone": "+254712345678"
}

Withdraw

POST /withdrawals
{
  "walletId": "uuid",
  "amount": 500,
  "provider": "mpesa",
  "phone": "+254712345678"
}

Create Escrow

POST /escrows
{
  "orderId": "uuid",
  "buyerWallet": "uuid",
  "sellerWallet": "uuid",
  "amount": 3000,
  "currency": "KES"
}

Release Escrow

POST /escrows/:id/release

Refund Escrow

POST /escrows/:id/refund
{
  "reason": "Item not as described"
}

---

Database Schema

-- Wallets
wallets (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL,
  currency VARCHAR(3) DEFAULT 'KES',
  balance DECIMAL(15,2) DEFAULT 0,
  created_at TIMESTAMP
)

-- Transactions
transactions (
  id UUID PRIMARY KEY,
  wallet_id UUID NOT NULL,
  type VARCHAR(20),  -- deposit, withdrawal, escrow_hold, escrow_release
  amount DECIMAL(15,2),
  balance_after DECIMAL(15,2),
  reference VARCHAR(100),
  status VARCHAR(20),
  created_at TIMESTAMP
)

-- Escrows
escrows (
  id UUID PRIMARY KEY,
  order_id UUID NOT NULL,
  buyer_wallet_id UUID NOT NULL,
  seller_wallet_id UUID NOT NULL,
  amount DECIMAL(15,2),
  fee DECIMAL(15,2),
  status VARCHAR(20),
  created_at TIMESTAMP,
  released_at TIMESTAMP
)

---

Fees

Transaction	Fee
Deposit	Free
Withdrawal	KES 10-50 (varies)
Escrow	5% (on release)
Transfer (Yebo→Yebo)	Free

---

Security

• Encryption: All financial data encrypted
• Audit log: Every transaction logged
• Reconciliation: Daily balance checks
• Fraud detection: Velocity checks, limits
• 2FA: PIN required for withdrawals

---

Build Plan

Week	Tasks
1	Wallet model, basic API
2	Transaction ledger
3	M-Pesa deposit (STK Push)
4	M-Pesa withdrawal (B2C)
5	Escrow logic
6	Testing, edge cases

---

Integration Points

Product	Uses YeboSafe For
YeboShops	Escrow, payments
YeboJobs	Salary, freelance pay
YeboNa	Supplier escrow
YeboLearn	Course payments
Agent	Balance checks, transfers