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

EndpointMethodeBeschrijvingAuth
/stripe/create-checkoutPOSTCheckout Session voor NFT mintCSRF-exempt
/stripe/buy-tokens-checkoutPOSTCheckout Session voor token purchaseCSRF-exempt
/stripe/webhookPOSTStripe webhook (signature check)Stripe signature

3. Tier configuratie

TierPrijs (cent)ModusBeschrijving
explorer0paymentFree tier
basic500paymentEenmalige NFT mint fee
pioneer500subscription5 EUR/maand
pro1000subscription5 EUR/maand + 5 EUR NFT fee
architect2000subscription20 EUR/maand
gold2000subscription15 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

8. Risico's en aanbevelingen

RisicoImpactMitigatie
Raw body signature-check kan stuk bij Hono updatesHighc.req.raw() gedocumenteerd en getest. Voeg integration test toe met echte Stripe webhook fixture.
Geen echte Stripe SDK calls (scaffold)HighKoppel stripe.checkout.sessions.create() zodra STRIPE_SECRET_KEY beschikbaar.
mintCache niet gekoppeldMediumImplementeer mintCache.set() voor free-tier mint flow.
getDiscountPercent retourneert altijd 0%MediumKoppel 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.