juxtapoandClaude Opus 5
a58a61b98c
A South African men's apparel store on Spree 5.6 + Next.js 15. 160 products
live, three markets, live Malaysian courier rates, customer-owned carts.
What is here:
storefront/ the Next.js app
backend/ ONLY the custom Spree code. Spree itself is a prebuilt image
that mounts no app code, so every file here needs an explicit
volume entry in docker-compose.yml or it is silently ignored.
catalogue/ the scripts that loaded and maintain the products
docs/ manifest, mock registry, napkins
Real .env files are committed deliberately. This lives on the house's private
Gitea, and a clone that runs beats a clone that needs a secrets handover.
LANDMINE.md maps every key, what it opens, and what must be rotated before this
repo goes anywhere less private.
The admin API key used to be a literal in six catalogue scripts. They now read
SPREE_ADMIN_KEY from the environment and refuse to run without it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
110 lines
3.7 KiB
Markdown
110 lines
3.7 KiB
Markdown
# 💳 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
|
||
```
|