Skip to content

E8-F1: Stripe Integration

Epic: E8: Payment Processing

Size: M (Medium)

Webhook delivery path

Stripe events reach the ticketing backend via a shared Stripe Webhook Router that verifies the Stripe signature once and publishes to the internal Event Bus. The backend's StripeWebhookController accepts Bearer-authenticated requests from the eventbus consumer and unwraps the envelope to access the original Stripe payload. For the router to route events here, PaymentService::createPaymentIntent sets metadata.site on every PaymentIntent to a value registered under the stripe.backend subject in the router's routes.yml.

Problem / Outcome

Integrate Stripe for card payments. Stripe checkout is already implemented in the HNS mobile app; the ticketing system needs webhook integration.

Scope

In-Scope:

  • Webhook handling (payment_intent.succeeded, payment_intent.payment_failed)
  • Refund API integration
  • Configuration via environment variables

Out-of-Scope:

  • Payment intent creation (handled by existing HNS mobile app Stripe implementation)
  • Alternative payment providers

Configuration

Stripe credentials provided via environment variables: - STRIPE_WEBHOOK_SECRET - STRIPE_API_KEY

Acceptance Criteria

  • AC1: Payment intent created with correct amount and metadata
  • AC2: Webhook updates order status on payment_intent.succeeded
  • AC3: Refund API processes refund to original payment method

Data Model Impact

Payment table:
- id (UUID, PK)
- order_id (UUID, FK)
- stripe_payment_intent_id (VARCHAR)
- stripe_charge_id (VARCHAR)
- amount (DECIMAL)
- currency (VARCHAR, default 'EUR')
- status (ENUM: pending, succeeded, failed, refunded)
- created_at (TIMESTAMP)
- completed_at (TIMESTAMP)

StripeWebhookLog table:
- id (UUID, PK)
- event_id (VARCHAR)
- event_type (VARCHAR)
- payload_json (JSONB)
- processed (BOOLEAN)
- processed_at (TIMESTAMP)
- error (VARCHAR, nullable)

Permissions/Roles

  • System

How to Verify

npm test -- --grep "stripe integration"

Expected: Payment flow works, webhooks processed.

Dependencies

  • None (external service)

Implementation Tasks

See E8: Payment Processing Tasks

Doc References

Last Updated: January 2026