pak-jabit/docs/napkin-payment-courier.md

💳 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