Formulaire public : paiement de la cotisation via l'API SumUp (remplace Yapla)

Remplace le simple lien Yapla statique par une vraie intégration API SumUp :
checkout hébergé créé à la soumission du formulaire, statut de paiement
(PENDING/PAID/FAILED/EXPIRED) tenu à jour par un webhook SumUp et visible sur
la fiche du bénévole. La cotisation n'est plus un montant unique : la
coordination configure autant de types de paiement qu'elle veut (libellé +
montant, ex. « Cotisation classique », « Mécénat »), et le bénévole en
choisit un à l'inscription — le libellé et le montant choisis sont figés sur
le bénévole, indépendamment d'une modification ultérieure de la config.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

backend/app/api/forms.py

@@ -2,11 +2,12 @@
 
 Deux familles d'endpoints sous le même routeur :
 - configuration (COORDINATION) : quels champs sont activés, formulaire
-  ouvert ou fermé ;
-- publics (**aucune authentification** — les seuls endpoints de toute
-  l'API dans ce cas) : consultation de la configuration et soumission,
-  protégés par hCaptcha (`app/forms/captcha.py`) et un filet de sécurité
-  global (`app/auth/rate_limit.py:form_submission_limiter`).
+  ouvert ou fermé, identifiants SumUp de paiement de la cotisation ;
+- publics (**aucune authentification**) : consultation de la configuration
+  et soumission (protégées par hCaptcha, `app/forms/captcha.py`, et un filet
+  de sécurité global, `app/auth/rate_limit.py:form_submission_limiter`), et
+  le webhook SumUp (`/public/sumup-webhook`, appelé par SumUp lui-même — pas
+  de hCaptcha possible serveur à serveur, voir `sumup_webhook` plus bas).
 
 Nom et prénom sont toujours collectés (indispensables à la création du
 bénévole) : ils ne font pas partie des champs activables, contrairement aux
@@ -20,6 +21,7 @@ coordination, faute de savoir si la personne visée est déjà inscrite (voir
 CLAUDE.md § 2, `Volunteer`)."""
 
 import json
+import logging
 import uuid
 
 from fastapi import (
@@ -33,33 +35,46 @@ from fastapi import (
     status,
 )
 from sqlalchemy import delete
+from sqlalchemy.exc import IntegrityError
 from sqlmodel import Session, select
 
-from app.api._common import set_artists, set_wished_positions
+from app.api._common import owned_or_404, set_artists, set_wished_positions
 from app.api.deps import get_edition
 from app.api.schemas import (
     FormFieldsSet,
+    FormPaymentOptionCreate,
+    FormPaymentOptionRead,
+    FormPaymentOptionUpdate,
     FormSubmissionResult,
     FormTemplateRead,
     FormTemplateUpdate,
     PublicArtistOption,
     PublicFormConfig,
+    PublicPaymentOption,
     PublicPositionOption,
+    SumUpWebhookPayload,
 )
 from app.auth.deps import require_coordinator
 from app.auth.rate_limit import form_submission_limiter
+from app.config import get_settings
 from app.db import get_session
 from app.forms import verify_hcaptcha
 from app.models import (
     Account,
     Artist,
     Edition,
+    FeePaymentStatus,
     FormField,
     FormFieldType,
+    FormPaymentOption,
     FormTemplate,
     Position,
     Volunteer,
+    local_now,
 )
+from app.sumup import create_checkout, get_checkout
+
+logger = logging.getLogger("app.forms")
 
 router = APIRouter(prefix="/editions/{edition_id}/form", tags=["form"])
 
@@ -95,6 +110,20 @@ def _enabled_fields(session: Session, edition_id: uuid.UUID) -> list[FormFieldTy
     )
 
 
+def _payment_options(session: Session, edition_id: uuid.UUID) -> list[FormPaymentOption]:
+    return list(
+        session.exec(
+            select(FormPaymentOption)
+            .where(FormPaymentOption.edition_id == edition_id)
+            .order_by(FormPaymentOption.order, FormPaymentOption.label)
+        )
+    )
+
+
+def _sumup_enabled(template: FormTemplate, options: list[FormPaymentOption]) -> bool:
+    return bool(template.sumup_merchant_code and template.sumup_api_key and options)
+
+
 def _template_read(template: FormTemplate, fields: list[FormFieldType]) -> FormTemplateRead:
     return FormTemplateRead(
         edition_id=template.edition_id,
@@ -102,7 +131,8 @@ def _template_read(template: FormTemplate, fields: list[FormFieldType]) -> FormT
         fields=fields,
         has_logo=template.logo is not None,
         description=template.description,
-        yapla_url=template.yapla_url,
+        sumup_merchant_code=template.sumup_merchant_code,
+        sumup_api_key_set=bool(template.sumup_api_key),
     )
 
 
@@ -140,11 +170,8 @@ def update_form(
 ) -> FormTemplateRead:
     template = _get_or_create_template(session, edition.id)
     changes = payload.model_dump(exclude_unset=True)
-    if changes.get("yapla_url"):
-        if not changes["yapla_url"].startswith(("http://", "https://")):
-            raise HTTPException(
-                status_code=422, detail={"code": "form.invalid_yapla_url"}
-            )
+    if changes.get("sumup_api_key") == "":
+        changes["sumup_api_key"] = None
     for field, value in changes.items():
         setattr(template, field, value)
     session.add(template)
@@ -152,6 +179,96 @@ def update_form(
     return _template_read(template, _enabled_fields(session, edition.id))
 
 
+# --------------------------------------------------------------------------- #
+# Types de paiement (COORDINATION) — voir `FormPaymentOption`                  #
+# --------------------------------------------------------------------------- #
+@router.get("/payment-options", response_model=list[FormPaymentOptionRead])
+def list_payment_options(
+    edition: Edition = Depends(get_edition),
+    _guard: Account = Depends(require_coordinator),
+    session: Session = Depends(get_session),
+) -> list[FormPaymentOption]:
+    return _payment_options(session, edition.id)
+
+
+@router.post(
+    "/payment-options",
+    response_model=FormPaymentOptionRead,
+    status_code=status.HTTP_201_CREATED,
+)
+def create_payment_option(
+    payload: FormPaymentOptionCreate,
+    edition: Edition = Depends(get_edition),
+    _guard: Account = Depends(require_coordinator),
+    session: Session = Depends(get_session),
+) -> FormPaymentOption:
+    if payload.amount <= 0:
+        raise HTTPException(
+            status_code=422, detail={"code": "form.invalid_sumup_amount"}
+        )
+    option = FormPaymentOption(
+        edition_id=edition.id,
+        label=payload.label.strip(),
+        amount=payload.amount,
+        order=payload.order,
+    )
+    session.add(option)
+    try:
+        session.commit()
+    except IntegrityError as exc:
+        session.rollback()
+        raise HTTPException(
+            status_code=409, detail={"code": "form.duplicate_payment_option_label"}
+        ) from exc
+    session.refresh(option)
+    return option
+
+
+@router.patch("/payment-options/{option_id}", response_model=FormPaymentOptionRead)
+def update_payment_option(
+    option_id: uuid.UUID,
+    payload: FormPaymentOptionUpdate,
+    edition: Edition = Depends(get_edition),
+    _guard: Account = Depends(require_coordinator),
+    session: Session = Depends(get_session),
+) -> FormPaymentOption:
+    option = owned_or_404(session.get(FormPaymentOption, option_id), edition.id)
+    changes = payload.model_dump(exclude_unset=True)
+    if changes.get("amount") is not None and changes["amount"] <= 0:
+        raise HTTPException(
+            status_code=422, detail={"code": "form.invalid_sumup_amount"}
+        )
+    if changes.get("label") is not None:
+        changes["label"] = changes["label"].strip()
+    for field, value in changes.items():
+        setattr(option, field, value)
+    session.add(option)
+    try:
+        session.commit()
+    except IntegrityError as exc:
+        session.rollback()
+        raise HTTPException(
+            status_code=409, detail={"code": "form.duplicate_payment_option_label"}
+        ) from exc
+    session.refresh(option)
+    return option
+
+
+@router.delete("/payment-options/{option_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_payment_option(
+    option_id: uuid.UUID,
+    edition: Edition = Depends(get_edition),
+    _guard: Account = Depends(require_coordinator),
+    session: Session = Depends(get_session),
+) -> Response:
+    option = owned_or_404(session.get(FormPaymentOption, option_id), edition.id)
+    # Les bénévoles ayant déjà choisi cette option gardent leur copie figée
+    # (`Volunteer.fee_payment_label`/`fee_amount`) — rien à faire côté eux.
+    session.delete(option)
+    session.commit()
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
 async def _read_logo(file: UploadFile) -> tuple[bytes, str]:
     content_type = file.content_type or ""
     if content_type not in _ALLOWED_PHOTO_TYPES:
@@ -233,6 +350,7 @@ def get_public_form(
             )
         ]
 
+    options = _payment_options(session, edition.id)
     return PublicFormConfig(
         is_open=template.is_open,
         fields=fields,
@@ -240,7 +358,10 @@ def get_public_form(
         artists=artists,
         has_logo=template.logo is not None,
         description=template.description,
-        yapla_url=template.yapla_url,
+        sumup_enabled=_sumup_enabled(template, options),
+        payment_options=[
+            PublicPaymentOption(id=o.id, label=o.label, amount=o.amount) for o in options
+        ],
     )
 
 
@@ -295,6 +416,7 @@ async def submit_public_form(
     companion_wish_note: str | None = Form(None),
     available: bool = Form(False),
     willing_to_pay_fee: bool = Form(False),
+    payment_option_id: str | None = Form(None),
     position_wish_ids: str | None = Form(None),
     artist_wish_ids: str | None = Form(None),
     photo: UploadFile | None = File(None),
@@ -335,6 +457,20 @@ async def submit_public_form(
     if artist_ids:
         _check_one_artist_wish_per_day(session, edition.id, artist_ids)
 
+    payment_option: FormPaymentOption | None = None
+    if FormFieldType.WILLING_TO_PAY_FEE in fields and payment_option_id:
+        try:
+            option_uuid = uuid.UUID(payment_option_id)
+        except ValueError:
+            option_uuid = None
+        payment_option = (
+            session.get(FormPaymentOption, option_uuid) if option_uuid else None
+        )
+        if payment_option is None or payment_option.edition_id != edition.id:
+            raise HTTPException(
+                status_code=422, detail={"code": "form.unknown_payment_option"}
+            )
+
     volunteer = Volunteer(
         edition_id=edition.id,
         first_name=first_name.strip().title(),
@@ -352,8 +488,13 @@ async def submit_public_form(
         self_declared_available=(
             available if FormFieldType.AVAILABLE in fields else False
         ),
+        # Choisir un type de paiement vaut « je participe » même sans cocher
+        # la case (le formulaire public n'affiche d'ailleurs plus qu'un choix
+        # unique dès qu'au moins un type est configuré, voir PublicSignupPage).
         willing_to_pay_fee=(
-            willing_to_pay_fee if FormFieldType.WILLING_TO_PAY_FEE in fields else False
+            (willing_to_pay_fee or payment_option is not None)
+            if FormFieldType.WILLING_TO_PAY_FEE in fields
+            else False
         ),
     )
 
@@ -382,4 +523,89 @@ async def submit_public_form(
 
     session.commit()
     session.refresh(volunteer)
-    return FormSubmissionResult(volunteer_id=volunteer.id)
+
+    checkout_url = None
+    if (
+        payment_option is not None
+        and template.sumup_merchant_code
+        and template.sumup_api_key
+    ):
+        checkout_url = _create_fee_checkout(
+            session, edition, template, volunteer, payment_option
+        )
+
+    return FormSubmissionResult(volunteer_id=volunteer.id, sumup_checkout_url=checkout_url)
+
+
+def _create_fee_checkout(
+    session: Session,
+    edition: Edition,
+    template: FormTemplate,
+    volunteer: Volunteer,
+    option: FormPaymentOption,
+) -> str | None:
+    """Crée le checkout SumUp du type de paiement choisi — best effort (comme
+    l'envoi d'emails) : un échec de l'appel API ne remet jamais en cause
+    l'inscription déjà enregistrée. `option.label`/`option.amount` sont
+    recopiés sur le bénévole (`fee_payment_label`/`fee_amount`) avant même
+    l'appel, pour garder une trace du choix même si l'appel échoue."""
+    volunteer.fee_payment_label = option.label
+    volunteer.fee_amount = option.amount
+
+    base = get_settings().public_base_url.rstrip("/")
+    checkout = create_checkout(
+        api_key=template.sumup_api_key,
+        merchant_code=template.sumup_merchant_code,
+        amount=option.amount,
+        currency="EUR",
+        checkout_reference=str(volunteer.id),
+        description=f"{option.label} — édition {edition.year}",
+        return_url=f"{base}/api/editions/{edition.id}/form/public/sumup-webhook",
+        redirect_url=f"{base}/inscription?paiement=ok",
+    )
+    if checkout is not None:
+        volunteer.fee_checkout_id = checkout.id
+        volunteer.fee_payment_status = FeePaymentStatus.PENDING
+    session.add(volunteer)
+    session.commit()
+    return checkout.hosted_checkout_url if checkout is not None else None
+
+
+@router.post("/public/sumup-webhook", status_code=status.HTTP_200_OK)
+def sumup_webhook(
+    payload: SumUpWebhookPayload,
+    edition: Edition = Depends(get_edition),
+    session: Session = Depends(get_session),
+) -> Response:
+    """Appelé par SumUp (aucune authentification possible côté SumUp) à
+    chaque changement de statut d'un checkout. Le payload ne donne qu'un
+    identifiant : jamais fait confiance sans relire l'état réel via l'API
+    (voir `app/sumup/client.py:get_checkout`). Répond toujours `200`, y
+    compris sur un événement inconnu — SumUp réessaie sinon inutilement."""
+    template = _get_or_create_template(session, edition.id)
+    if template.sumup_api_key:
+        checkout = get_checkout(api_key=template.sumup_api_key, checkout_id=payload.id)
+        volunteer = (
+            session.exec(
+                select(Volunteer).where(
+                    Volunteer.edition_id == edition.id,
+                    Volunteer.fee_checkout_id == payload.id,
+                )
+            ).first()
+            if checkout is not None
+            else None
+        )
+        if checkout is not None and volunteer is not None:
+            try:
+                new_status = FeePaymentStatus(checkout.status)
+            except ValueError:
+                new_status = None
+            if new_status is not None:
+                volunteer.fee_payment_status = new_status
+                if new_status == FeePaymentStatus.PAID and volunteer.fee_paid_at is None:
+                    volunteer.fee_paid_at = local_now()
+                session.add(volunteer)
+                session.commit()
+        elif checkout is None:
+            logger.warning("Webhook SumUp : relecture du checkout impossible.")
+    return Response(status_code=status.HTTP_200_OK)

backend/app/api/schemas.py

@@ -9,6 +9,7 @@ from app.models import (
     AssignmentSource,
     BadgeAlign,
     BadgeFieldType,
+    FeePaymentStatus,
     FormFieldType,
     PositionCategory,
     Role,
@@ -92,6 +93,15 @@ class VolunteerRead(ApiModel):
     companion_wish_note: str | None
     self_declared_available: bool
     willing_to_pay_fee: bool
+    # Paiement de la cotisation via SumUp (voir CLAUDE.md § 2, `Volunteer`) —
+    # `fee_payment_label`/`fee_amount` : copie figée du type de paiement
+    # choisi (pas la config actuelle, qui peut avoir changé depuis).
+    # `fee_payment_status` reste `None` tant qu'aucun checkout n'a jamais été
+    # créé pour ce bénévole.
+    fee_payment_label: str | None
+    fee_amount: float | None
+    fee_payment_status: FeePaymentStatus | None
+    fee_paid_at: dt.datetime | None
     created_at: dt.datetime
     updated_at: dt.datetime
 
@@ -493,16 +503,43 @@ class FormTemplateRead(ApiModel):
     fields: list[FormFieldType]
     has_logo: bool
     description: str | None
-    yapla_url: str | None
+    sumup_merchant_code: str | None
+    # `sumup_api_key` (secret) n'est jamais renvoyé — seulement s'il est
+    # défini, comme `has_logo` pour le logo.
+    sumup_api_key_set: bool
 
 
 class FormTemplateUpdate(ApiModel):
     """`None`/absent = inchangé pour chaque champ (`exclude_unset`) — permet
-    de changer `is_open` sans toucher `description`/`yapla_url`, etc."""
+    de changer `is_open` sans toucher `description`/`sumup_*`, etc. Chaîne
+    vide sur `sumup_api_key` = efface le secret enregistré."""
 
     is_open: bool | None = None
     description: str | None = None
-    yapla_url: str | None = None
+    sumup_merchant_code: str | None = None
+    sumup_api_key: str | None = None
+
+
+class FormPaymentOptionRead(ApiModel):
+    id: uuid.UUID
+    edition_id: uuid.UUID
+    label: str
+    amount: float
+    order: int
+    created_at: dt.datetime
+    updated_at: dt.datetime
+
+
+class FormPaymentOptionCreate(ApiModel):
+    label: str
+    amount: float
+    order: int = 0
+
+
+class FormPaymentOptionUpdate(ApiModel):
+    label: str | None = None
+    amount: float | None = None
+    order: int | None = None
 
 
 class PublicPositionOption(ApiModel):
@@ -516,6 +553,15 @@ class PublicArtistOption(ApiModel):
     performance_date: dt.date
 
 
+class PublicPaymentOption(ApiModel):
+    """Type de paiement proposé au bénévole sur le formulaire public — un
+    montant n'est pas un secret, contrairement aux identifiants SumUp."""
+
+    id: uuid.UUID
+    label: str
+    amount: float
+
+
 class PublicFormConfig(ApiModel):
     """Tout ce qu'il faut pour afficher le formulaire public — jamais plus :
     ni les bénévoles déjà inscrits, ni les créneaux/affectations de
@@ -527,8 +573,26 @@ class PublicFormConfig(ApiModel):
     artists: list[PublicArtistOption]
     has_logo: bool
     description: str | None
-    yapla_url: str | None
+    # `True` si l'édition a configuré SumUp (identifiants marchand + au
+    # moins un type de paiement) — utilisé par le front-end pour afficher le
+    # choix de paiement près de `WILLING_TO_PAY_FEE`, sans jamais exposer les
+    # identifiants eux-mêmes.
+    sumup_enabled: bool
+    payment_options: list[PublicPaymentOption]
 
 
 class FormSubmissionResult(ApiModel):
     volunteer_id: uuid.UUID
+    # Lien de paiement hébergé SumUp, si un checkout a pu être créé (voir
+    # `app/api/forms.py:submit_public_form`) — `None` si le bénévole n'a
+    # choisi aucun type de paiement, si SumUp n'est pas configuré, ou en cas
+    # d'échec de l'appel API (best effort, l'inscription reste valide).
+    sumup_checkout_url: str | None = None
+
+
+class SumUpWebhookPayload(ApiModel):
+    """Corps envoyé par SumUp à `return_url` — voir la doc SumUp sur les
+    webhooks. Le seul événement existant à ce jour."""
+
+    event_type: str
+    id: str

backend/app/api/volunteers.py

@@ -99,7 +99,9 @@ def _companion_ids(session: Session, volunteer_id: uuid.UUID) -> list[uuid.UUID]
 
 def _read(session: Session, volunteer: Volunteer) -> VolunteerRead:
     return VolunteerRead(
-        **volunteer.model_dump(exclude={"photo", "photo_content_type"}),
+        **volunteer.model_dump(
+            exclude={"photo", "photo_content_type", "fee_checkout_id"}
+        ),
         artist_ids=_artist_ids(session, volunteer.id),
         wished_position_ids=_wished_position_ids(session, volunteer.id),
         wished_companion_ids=_companion_ids(session, volunteer.id),