API: Stripe-routes
Ticket 1A-03 • Bron: src/routes/stripe.ts • Status: geimplementeerd (scaffold) • Risico: hoog (webhook-verificatie)
Kerndefinitie: Drie Stripe-endpoints voor NFT mint checkout, token purchase en webhook-verificatie. De webhook route is kritiek: c.req.raw() moet bewaard blijven voor raw body signature-check. Checkout-routes ondersteunen kortingen via on-chain wallet-data en free-tier handling.
1. Architectuur
Client (Wallet-DApp / Browser)
│
├── POST /stripe/create-checkout
│ ├── Valideer tier + wallet + did
│ ├── On-chain korting ophalen (getDiscountPercent)
│ ├── applyDiscountPercent(unitAmount, discount)
│ ├── FREE TIER (amount=0)? → direct mint
│ ├── DEV MODE (_devSkipPayment)? → fake sessie
│ └── Prod: Stripe Checkout Session aanmaken
│
├── POST /stripe/buy-tokens-checkout
│ ├── Valideer wallet + amount (EUR)
│ ├── Bereken MAOS tokens: amount * 100
│ ├── DEV MODE? → fake sessie
│ └── Prod: Stripe Checkout Session aanmaken
│
└── POST /stripe/webhook
├── c.req.raw() → arrayBuffer() voor raw body
├── stripe-signature header
├── stripe.webhooks.constructEvent(buf, sig, secret)
└── Event afhandelen (checkout.session.completed, etc.)
KRITIEK: /webhook behoudt raw body. Hono c.req.raw() = originele Request.
2. Endpoints
| Endpoint | Methode | Beschrijving | Auth |
/stripe/create-checkout | POST | Checkout Session voor NFT mint | CSRF-exempt |
/stripe/buy-tokens-checkout | POST | Checkout Session voor token purchase | CSRF-exempt |
/stripe/webhook | POST | Stripe webhook (signature check) | Stripe signature |
3. Tier configuratie
| Tier | Prijs (cent) | Modus | Beschrijving |
explorer | 0 | payment | Free tier |
basic | 500 | payment | Eenmalige NFT mint fee |
pioneer | 500 | subscription | 5 EUR/maand |
pro | 1000 | subscription | 5 EUR/maand + 5 EUR NFT fee |
architect | 2000 | subscription | 20 EUR/maand |
gold | 2000 | subscription | 15 EUR/maand + 5 EUR NFT fee |
4. Request / Response voorbeelden
4.1 POST /stripe/create-checkout
POST /stripe/create-checkout HTTP/1.1
Content-Type: application/json
{
"tier": "pro",
"wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
"did": "did:maos:0x742d35Cc..."
}
Response (prod):
{
"sessionId": "cs_1234567890_abc",
"url": "https://checkout.stripe.com/pay/cs_...",
"discountPercent": 15,
"discountApplied": true,
"originalAmount": 1000,
"unitAmount": 850,
"savings": 150
}
Response (free tier):
{
"sessionId": "free_1234567890_abc",
"freeMint": true,
"discountPercent": 0,
"discountApplied": false,
"originalAmount": 0,
"unitAmount": 0,
"savings": 0
}
4.2 POST /stripe/buy-tokens-checkout
POST /stripe/buy-tokens-checkout HTTP/1.1
Content-Type: application/json
{
"wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
"amount": 50
}
→ 50 EUR * 100 = 5000 MAOS tokens
Response:
{
"sessionId": "cs_1234567890_abc",
"url": "https://checkout.stripe.com/pay/cs_..."
}
4.3 POST /stripe/webhook
POST /stripe/webhook HTTP/1.1
Content-Type: application/json
Stripe-Signature: t=1234567890,v1=abc123...
Raw body wordt gelezen via c.req.raw().arrayBuffer()
→ stripe.webhooks.constructEvent(buf, signature, webhookSecret)
→ Event type afhandelen
Response:
{ "received": true }
4.4 Foutafhandeling
// Ongeldig tier
POST /stripe/create-checkout { "tier": "unknown", ... }
→ 400 { "error": "Invalid tier: unknown" }
// Ongeldig wallet-adres
POST /stripe/create-checkout { "tier": "pro", "wallet": "abc" }
→ 400 { "error": "Invalid wallet address" }
// Webhook secret niet geconfigureerd
POST /stripe/webhook
→ 500 { "error": "Webhook secret not configured" }
5. Kortingsflow
On-chain korting ophalen:
1. getDiscountPercent(wallet) → percentage (0-100)
2. applyDiscountPercent(unitAmount, percentage)
└── Math.round((unitAmount * (100 - pct)) / 100)
3. discountApplied = (pct > 0 && discounted < original)
4. savings = original - discounted
Fallback: fout bij ophalen korting → 0% (volle prijs)
Wallet regex: /^0x[0-9a-fA-F]{40}$/
6. DEV-mode
Development-mode: Wanneer NODE_ENV=development + _devSkipPayment: true in body, retourneren checkout-routes een fake sessie met redirect-URL naar /payment-success. Dit vermijdt echte Stripe-calls tijdens ontwikkeling.
7. Acceptatiecriteria
- Webhook-verificatie met Stripe-signature blijft werken (raw body behouden)
- Checkout-sessie aanmaak geeft correcte redirect-URL
- Discount lookup (on-chain getDiscount) blijft best-effort (geen fout bij falen)
- FREE TIER (amount=0) geeft
freeMint: true terug
- Token purchase berekent MAOS tokens = EUR * 100
- DEV-mode retourneert fake sessies zonder Stripe-calls
- Validatie: wallet regex, tier check, amount check
8. Risico's en aanbevelingen
| Risico | Impact | Mitigatie |
| Raw body signature-check kan stuk bij Hono updates | High | c.req.raw() gedocumenteerd en getest. Voeg integration test toe met echte Stripe webhook fixture. |
| Geen echte Stripe SDK calls (scaffold) | High | Koppel stripe.checkout.sessions.create() zodra STRIPE_SECRET_KEY beschikbaar. |
| mintCache niet gekoppeld | Medium | Implementeer mintCache.set() voor free-tier mint flow. |
| getDiscountPercent retourneert altijd 0% | Medium | Koppel on-chain getDiscount via viem publicClient. |
9. Verwijzingen
Fase 1A Implementatie in src/routes/stripe.ts. Scaffold met placeholders voor Stripe SDK. Webhook-structuur behouden. Risico: raw body signature-check moet getest worden met echte Stripe fixtures.