Payment Integration System (Issue #84)

Overview

KoproGo integrates with Stripe Payment Intents and SEPA Direct Debit for secure payment processing. The system handles the full transaction lifecycle from creation through refund, with PCI-DSS compliance via Stripe tokenization.

Belgian Context

  • EUR only: All transactions in Euros (Belgian market)

  • SEPA Direct Debit: Primary payment method for Belgian bank accounts

  • Belgian IBAN validation: BE + 14 digits format

Transaction Lifecycle

Pending → Processing → RequiresAction → Succeeded
                            ↓              ↓
                          Failed      Refunded (partial/full)
                            ↓
                        Cancelled

Payment Methods

Type

Description

Card

Visa, Mastercard (Stripe)

SepaDebit

Belgian IBAN mandate

BankTransfer

Manual wire transfer

Cash

In-person payment

Key Features

  • Idempotency keys: Prevent duplicate charges on retry (min 16 chars)

  • PCI-DSS: No raw card data stored, only Stripe tokens (pm_xxx)

  • Refunds: Partial and full refunds with anti-over-refund validation

  • Default management: One default payment method per owner (atomic)

  • Statistics: Total paid, net amount, per owner/building/expense

API Endpoints (38 total)

Payments (22 endpoints):

  • POST /payments - Create payment

  • GET /payments/:id - Get payment

  • GET /owners/:id/payments - Owner payments

  • GET /buildings/:id/payments - Building payments

  • PUT /payments/:id/succeeded - Mark succeeded

  • POST /payments/:id/refund - Process refund

  • GET /owners/:id/payments/stats - Owner statistics

Payment Methods (16 endpoints):

  • POST /payment-methods - Create

  • GET /owners/:id/payment-methods - List owner methods

  • PUT /payment-methods/:id/set-default - Set default

  • PUT /payment-methods/:id/deactivate - Deactivate

Architecture

  • Domain: payment.rs (530 lines), payment_method.rs (273 lines)

  • Use Cases: payment_use_cases.rs (26 methods), payment_method_use_cases.rs (14 methods)

  • Migration: 20251118000000_create_payments.sql

  • BDD Tests: payments.feature + payment_methods.feature (28 scenarios)

  • Total: ~5,500 lines of code, 38 REST endpoints