# 💳 Payment & Courier — Napkin Notes

## Payment Gateways (SA Market)

### Recommended Stack
| Gateway | What it covers | Fees | Priority |
|---------|---------------|------|----------|
| **Payfast** | Cards (Visa/MC), EFT, SnapScan, Masterpass | 3.5% + R2/tx | Must-have |
| **Payflex** | Buy now pay later (4 instalments) | They pay you upfront | High — big conversion booster for fashion |
| **Yoco** | Cards, tap-to-pay (if physical retail later) | 2.6-2.95%/tx | Nice-to-have |

### Why this stack
- Payfast alone covers ~90% of SA payment methods
- Payflex is the killer feature for apparel — "R1,500 jacket? Pay R375 × 4" removes price friction
- Cards (Visa/MC/Amex) come free with Payfast
- EFT = still king in SA, people trust bank transfers

### NOT needed (yet)
- Stripe — limited SA support, overkill for local-first
- PayPal — high fees, withdrawal pain in SA
- Crypto — niche, not the market

### Integration notes
- Spree has payment provider plugin architecture — write adapter, plug in API keys
- Morne's company (NSH/INET) registers as merchant — they get the API keys
- We build the pipe, they plug in credentials
- Payfast has well-documented REST API + existing Spree community plugins

---

## Courier / Logistics (SA Market)

### Recommended: Bob Go (aggregator)
- **One API** → connects to 10+ SA couriers
- API docs: https://api-docs.bob.co.za/bobgo
- Couriers included: The Courier Guy, Pargo, RAM, SkyNet, Internet Express, DPD/Dawn Wing
- Features: compare rates, print waybills, track parcels
- Shopify integration exists → Spree adapter needed

### What Bob Go solves (all 3 spec blockers)
| Spec Action Item | Status |
|-----------------|--------|
| 🔴 Identify suitable SA courier/API | ✅ Bob Go = one API, all couriers |
| 🔴 Confirm automated shipment creation | ✅ Bob Go API supports it |
| 🔴 Confirm waybill generation | ✅ Bob Go handles waybills |

### Direct courier alternatives (if Bob Go doesn't fit)
- **The Courier Guy** — most popular SA e-commerce courier
- **Internet Express** — free API integration
- **CourierIT** — volume discounts
- **Evership** — another aggregator (Fastway, RAM, Aramex, TCG, DPD)

### Shipping zones consideration
- SA is big — courier coverage varies by province
- Major metros (Joburg, Cape Town, Durban) = next day
- Rural = 3-5 days, some couriers don't cover
- Bob Go handles zone logic per courier

---

## 🏷️ Mock Convention

All test/sandbox values tagged with `#mock` in code and config.
When going live: `rg '#mock'` → find all → replace with production credentials.

```
# Example in config:
PAYFAST_MERCHANT_ID=10000100  #mock
PAYFAST_MERCHANT_KEY=46f0cd694581a      #mock
PAYFAST_PASSPHRASE=jt7NOE43FZPn        #mock
PAYFAST_MODE=sandbox                     #mock → change to "live"
BOBGO_API_KEY=test_xxxxxxxxxxxx          #mock
PAYFLEX_API_KEY=staging_xxxxx            #mock
```

---

## Open Questions
- [ ] Local SA only or international shipping?
- [ ] Currency: ZAR only or multi-currency?
- [ ] Who registers as merchant — NSH or a new entity?
- [ ] Cash on delivery — needed? (Still popular outside metros)
- [ ] Payflex merchant approval — timeline?

---

## Architecture Summary

```
Buyer → Spree Storefront (Next.js)
         ↓
       Checkout
         ↓
    ┌────┴────┐
    │ Payfast │ → Cards, EFT, SnapScan
    │ Payflex │ → Buy now pay later
    └────┬────┘
         ↓
    Order Created
         ↓
    Bob Go API → auto-select cheapest courier
         ↓
    ┌────┴────┐
    │ Waybill │ → PDF generated
    │ Tracking│ → number assigned
    └────┬────┘
         ↓
    Customer gets tracking link
```