# Sponzar EventOS & Marketplace — Vendor Operations & Integration Guide

> **Target Audience:** Event Vendors, Exhibitors, Creative Service Providers, and Event Organizers  
> **Platform Surface:** Sponzar Global Marketplace & EventOS Infrastructure  
> **Workspace Portal:** `https://sponzar.africa/vendor/dashboard` & `https://sponzar.africa/vendor-catalog`

---

## 1. Overview & Architecture

Sponzar transforms fragmented event vendor operations into bankable, verified enterprise records. Vendors providing services—such as **Catering & Mobile Bars, Security & Bouncers, Stage Audio/Visual, and Logistics/Decor**—can:
1. List verified business profiles on Sponzar's global marketplace.
2. Get hired by event creators with funds held safely in **Sponzar Escrow**.
3. Operate on-site event stalls with digital order taking and staff POS registers.
4. Settle revenue directly to verified South African bank accounts.
5. Embed their service catalogue on their own external websites or event organizer sites.

---

## 2. Vendor Onboarding & KYC Verification

### 2.1 Eligibility & KYC Requirement
In accordance with Sponzar's **Data Accuracy Contract** and enterprise security standards, all vendors must complete Identity Verification (KYC) before listing services.

1. Log in to your Sponzar account (`https://sponzar.africa/login`).
2. Navigate to **Account Settings → Verification** and submit:
   * South African National ID or Passport.
   * Proof of Business Registration (CIPC certificate if registered) or trading name.
3. Once verified, visit the Vendor Onboarding portal:  
   👉 **`https://sponzar.africa/vendor/onboarding`**

### 2.2 Creating Your Business Profile
Complete the profile questionnaire:
* **Business Name:** Must be unique and reflect your trading entity.
* **Category:** Choose from `Security`, `Catering`, `Audio/Visual`, or `Logistics`.
* **Description:** Detail your team capacity, equipment specs, and operational history.
* **Portfolio URL:** Link to past event photos, social proof, or media references.

---

## 3. Service Catalogue & Pricing Structures

Vendors can offer multiple packages with flexible pricing units:

| Pricing Model | Description | Example Use Case |
|---|---|---|
| `per hour` | Billed per duration of service | Sound technician, videographer |
| `per day` | Full day day-rate | VIP Security guard, event host |
| `per event` | Flat contract price for the entire event | Stage lighting package, main PA system |
| `per unit` | Per item or attendee count | Catering meal packs, branded lanyard sets |

### Adding a Service via Dashboard
1. Go to **Vendor Dashboard → Services** (`/vendor/dashboard`).
2. Click **Add Service**.
3. Input Title, Description, Base Price in ZAR, and Pricing Type.
4. Toggle **Active** to publish instantly to the global catalogue.

---

## 4. Escrow Hiring Engine & Contract Flow

When an event organizer or creator books your service, Sponzar uses an automated Escrow protocol to protect both parties:

```mermaid
graph TD
    A[Creator selects service on Marketplace] --> B[Escrow Contract Created Pending]
    B --> C[Creator Funds Escrow via Ozow / Paystack]
    C --> D[Vendor receives booking notification & prepares service]
    D --> E[Service delivered at live event]
    E --> F[Organizer confirms completion OR milestone expires]
    F --> G[Funds released instantly to Vendor Sponzar Wallet]
```

### Escrow Guarantees:
* **Guaranteed Payment:** Vendors never perform work on unverified promises; funds are locked before arrival.
* **Transparent Fees:** 5% standard platform escrow processing fee.
* **Dispute Resolution:** Sponzar platform arbitration protects against last-minute cancellations.

---

## 5. EventOS On-Site Stall Operations & Staff POS

For food vendors, merchandise stalls, and festival exhibitors:

### 5.1 Operating the Cashless POS
1. Open the vendor register interface: `https://sponzar.africa/event-os/vendor/{vendor_id}/pos`.
2. Browse products or enter manual charge amounts.
3. Attendees pay using their event digital wallet or NFC wristband.
4. Orders route automatically to the kitchen/prep screen.

### 5.2 Staff PIN Management
Issue sub-accounts for register operators:
1. Navigate to **Vendor Dashboard → Staff Management** (`/event-os/vendor/{vendor_id}/staff`).
2. Click **Add Staff Member** and assign operator name and 4-digit PIN.
3. Staff members log in at `/event-os/vendor/{vendor_id}/pos/login` using their personal PIN.

---

## 6. Embedding Vendor Services on External Websites

Vendors and event organizers can embed the marketplace catalog or single vendor services on external websites using three methods:

### 6.1 Method 1: Sponzar Embed SDK Web Component
Embed the interactive vendor widget on any custom HTML, Webflow, or Squarespace page:

```html
<!-- Include SDK script in head -->
<script src="https://sponzar.africa/sdk/sdk.js" data-token="emb_live_your_token"></script>

<!-- Embed All Catering Vendors -->
<sponzar-vendors category="Catering" theme="dark"></sponzar-vendors>

<!-- Embed a Single Specific Vendor -->
<sponzar-vendor id="5" theme="dark"></sponzar-vendor>
```

### 6.2 Method 2: WordPress Shortcode (`sponzar-connect`)
On WordPress websites with the Sponzar Connect plugin:

```text
[sponzar_vendors category="Security" columns="3"]
```

### 6.3 Method 3: Headless Developer API v1
Fetch active vendors programmatically:

```http
GET /api/v1/vendors?category=Catering&per_page=10 HTTP/1.1
Host: sponzar.africa
X-Api-Key: sk_live_your_key_here
Accept: application/json
```

---

## 7. Wallet Settlements & Bank Withdrawals

1. View live event balance under **Vendor Dashboard → Settlements**.
2. Click **Request Settlement**.
3. Enter amount and select linked South African bank account (FNB, Standard Bank, Capitec, Nedbank, Absa).
4. Payouts are reconciled to the cent against event ledger entries and transferred via EFT.