API Documentatie

Je bent een senior TypeScript/Next.js developer.

Doel: integreer de WolffPay API in mijn webshop op een veilige, robuuste manier.

Bronnen van waarheid:
- OpenAPI spec: https://api.bywolff.dev/api/openapi
- Idempotency is verplicht voor alle POST requests (Idempotency-Key 8-255 chars)
- Webhooks komen binnen met headers: X-WolffPay-Signature, X-WolffPay-Event, X-WolffPay-Delivery-Attempt
- Webhook body is JSON: { event, data, timestamp }

Eisen:
- Schrijf type-safe code (TypeScript types voor requests/responses)
- Voeg retry + exponential backoff toe voor 429/5xx (maar nooit dubbel betalen: respecteer idempotency)
- Verifieer webhook signatures timing-safe (hex HMAC) en reject bij invalid signature
- Hou implementatie minimal en production-ready (geen pseudocode)
- Terminal betalingen: gebruik POST /api/v1/payments/terminal met action veld (create_intent, collect_and_process, etc.)

Lever op:
- Een kleine client wrapper (fetch-based) voor payments + refunds + terminal
- Een Next.js route handler voorbeeld voor webhooks (signature verification)

Taak: maak een functie createPayment() die:
- POST /api/v1/payments aanroept
- headers zet: Authorization, Content-Type, Idempotency-Key
- een idempotency key maakt per order attempt (deterministisch per orderId+attempt)
- errors netjes mapped naar een bruikbare error (met status + message)
- return type: { id, clientSecret, status, ... } (type-safe)

Taak: maak een webhook handler die:
- raw body leest
- X-WolffPay-Signature verifieert (t=..., v1=<hex>) met HMAC-SHA256 over "{timestamp}.{rawBody}"
- tolerance 300s gebruikt
- switch op event.event: payment.succeeded | payment.failed | payment.refunded
- altijd snel 2xx returned en verwerking async kan doen

// Haal WolffPay configuratie op
const response = await fetch('https://api.bywolff.dev/api/config', {
  headers: {
    'Authorization': 'Bearer wp_test_...'
  }
});

const config = await response.json();

// Response bevat:
// {
//   "success": true,
//   "data": {
//     "stripePublishableKey": "pk_test_...",  // Platform key
//     "stripeAccountId": "acct_...",          // Connected account ID
//     "chargesEnabled": true,
//     "supportedPaymentMethods": ["card", "ideal", "sepa_debit"]
//   }
// }

import { loadStripe } from '@stripe/stripe-js';

// ❌ FOUT - Dit geeft "Invalid API Key" error
const stripe = loadStripe(config.data.stripePublishableKey);

// ✅ CORRECT - Met stripeAccount parameter
const stripe = loadStripe(config.data.stripePublishableKey, {
  stripeAccount: config.data.stripeAccountId  // VERPLICHT!
});

import { Elements, PaymentElement } from '@stripe/react-stripe-js';
import { loadStripe } from '@stripe/stripe-js';

function CheckoutPage() {
  const [stripePromise, setStripePromise] = useState(null);
  const [clientSecret, setClientSecret] = useState('');

  useEffect(() => {
    // Haal config op
    fetch('https://api.bywolff.dev/api/config', {
      headers: { 'Authorization': 'Bearer wp_test_...' }
    })
      .then(res => res.json())
      .then(config => {
        // Initialiseer Stripe MET stripeAccount
        const stripe = loadStripe(config.data.stripePublishableKey, {
          stripeAccount: config.data.stripeAccountId
        });
        setStripePromise(stripe);
      });

    // Maak payment intent
    fetch('https://api.bywolff.dev/api/v1/payments', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer wp_test_...',
        'Content-Type': 'application/json',
        'Idempotency-Key': 'order-123'
      },
      body: JSON.stringify({
        amount: 5000,
        currency: 'eur',
        description: 'Order #123'
      })
    })
      .then(res => res.json())
      .then(data => setClientSecret(data.data.clientSecret));
  }, []);

  if (!stripePromise || !clientSecret) {
    return <div>Loading...</div>;
  }

  return (
    <Elements stripe={stripePromise} options={{ clientSecret }}>
      <PaymentElement />
      <button type="submit">Betalen</button>
    </Elements>
  );
}

{
  "event": "payment.succeeded",
  "data": {
    "id": "pi_abc123",
    "amount": 5000,
    "currency": "eur",
    "description": "Order #12345",
    "status": "succeeded",
    "metadata": {
      "order_id": "12345",
      "customer_email": "klant@example.com"
    }
  },
  "timestamp": "2026-02-18T12:34:56.789Z"
}

POST /api/webhooks/wolffpay
Content-Type: application/json
X-WolffPay-Signature: t=1734355200,v1=a1b2c3d4e5f6...
X-WolffPay-Event: payment.succeeded
X-WolffPay-Delivery-Attempt: 1

{
  "event": "payment.succeeded",
  ...
}

import crypto from 'crypto';

const WEBHOOK_SECRET = process.env.WOLFFPAY_WEBHOOK_SECRET!;
const TOLERANCE_SECONDS = 300; // 5 minuten

function verifyWebhookSignature(
  rawBody: string, 
  signatureHeader: string
): boolean {
  // 1. Parse signature header
  const parts = signatureHeader.split(',');
  let timestamp = '';
  let expectedSignature = '';
  
  for (const part of parts) {
    const [key, value] = part.split('=');
    if (key === 't') timestamp = value;
    if (key === 'v1') expectedSignature = value;
  }
  
  if (!timestamp || !expectedSignature) {
    return false;
  }
  
  // 2. Check timestamp (bescherming tegen replay attacks)
  const now = Math.floor(Date.now() / 1000);
  const timestampAge = Math.abs(now - parseInt(timestamp));
  
  if (timestampAge > TOLERANCE_SECONDS) {
    console.error('Webhook timestamp te oud:', timestampAge, 'seconden');
    return false;
  }
  
  // 3. Construeer signed payload
  const signedPayload = `${timestamp}.${rawBody}`;
  
  // 4. Bereken HMAC-SHA256 signature
  const computedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(signedPayload)
    .digest('hex');
  
  // 5. Vergelijk signatures (timing-safe)
  try {
    return crypto.timingSafeEqual(
      Buffer.from(computedSignature, 'hex'),
      Buffer.from(expectedSignature, 'hex')
    );
  } catch {
    return false;
  }
}

// app/api/webhooks/wolffpay/route.ts
import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';

const WEBHOOK_SECRET = process.env.WOLFFPAY_WEBHOOK_SECRET!;
const TOLERANCE_SECONDS = 300;

function verifySignature(body: string, signature: string): boolean {
  const parts = signature.split(',');
  const timestamp = parts.find(p => p.startsWith('t='))?.split('=')[1];
  const expectedSig = parts.find(p => p.startsWith('v1='))?.split('=')[1];
  
  if (!timestamp || !expectedSig) return false;
  
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > TOLERANCE_SECONDS) {
    return false;
  }
  
  const signedPayload = `${timestamp}.${body}`;
  const computed = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(signedPayload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(computed, 'hex'),
    Buffer.from(expectedSig, 'hex')
  );
}

export async function POST(request: NextRequest) {
  try {
    // 1. Lees raw body (belangrijk!)
    const body = await request.text();
    const signature = request.headers.get('X-WolffPay-Signature');
    
    // 2. Verifieer signature
    if (!signature || !verifySignature(body, signature)) {
      console.error('Invalid webhook signature');
      return NextResponse.json(
        { error: 'Invalid signature' }, 
        { status: 401 }
      );
    }
    
    // 3. Parse event
    const event = JSON.parse(body);
    console.log('Webhook verified:', event.event);
    
    // 4. Handle event types
    switch (event.event) {
      case 'payment.succeeded':
        await handlePaymentSuccess(event.data);
        break;
        
      case 'payment.failed':
        await handlePaymentFailed(event.data);
        break;
        
      case 'payment.refunded':
        await handleRefund(event.data);
        break;
        
      default:
        console.log('Unhandled event type:', event.event);
    }
    
    // 5. Return 200 snel (binnen 5 seconden)
    return NextResponse.json({ received: true });
    
  } catch (error) {
    console.error('Webhook error:', error);
    return NextResponse.json(
      { error: 'Webhook handler failed' },
      { status: 500 }
    );
  }
}

async function handlePaymentSuccess(paymentIntent: any) {
  const orderId = paymentIntent.metadata?.order_id;
  console.log('Payment succeeded for order', orderId);
  
  // TODO: Update order status in database
  // TODO: Send confirmation email
  // TODO: Fulfill order
}

async function handlePaymentFailed(paymentIntent: any) {
  const orderId = paymentIntent.metadata?.order_id;
  console.log('Payment failed for order', orderId);
  
  // TODO: Update order status
  // TODO: Notify customer
}

async function handleRefund(refund: any) {
  console.log('Refund processed');
  
  // TODO: Update order status
  // TODO: Notify customer
}

# Start ngrok tunnel
ngrok http 3000

# Output: https://abc123.ngrok.io

# Update webhook URL in WolffPay dashboard:
# https://abc123.ngrok.io/api/webhooks/wolffpay