feat: add pluggable payment system with Stripe provider

Three-layer payment architecture:
- PaymentProvider ABC (payments/base.py): defines provider interface with
  create/confirm/webhook/refund lifecycle methods, PaymentFlow (INLINE/REDIRECT),
  PaymentStatus enum, and PaymentResult dataclass
- Provider Registry (payments/registry.py): register_provider() for
  self-registration in AppConfig.ready(), get_provider(), get_available_providers()
- Stripe Provider (payments/stripe_provider.py): INLINE flow using
  PaymentIntents with automatic_payment_methods

Models:
- PaymentRecord: tracks payment lifecycle per submission (provider, transaction_id,
  amount, currency, status, idempotency_key)
- 7 payment config fields on FormDefinition (enabled, provider, amount_type,
  fixed_amount, amount_field, currency, description_template)
- pending_payment status on FormSubmission

View flow: form validates -> save as pending_payment -> initiate_payment ->
provider creates payment -> inline page or external redirect -> confirmation ->
_finalize_submission() triggers workflow

5 URL endpoints: initiate, confirm, return (redirect flow), cancel, webhook

Also includes:
- Form builder UI: payment section with provider dropdown, amount type, currency
- Admin: PaymentRecordAdmin (read-only) + PaymentRecordInline on submissions,
  Payment fieldset on FormDefinitionAdmin
- sync_api: payment fields in export/import serialization
- clone_forms: payment fields included in form cloning
- JS: payment-stripe.js for Stripe Elements integration
- Templates: payment_collect.html, payment_error.html
- Migration 0085
- 28 new tests (model, registry, views, provider, data structures)

Co-authored-by: Claude Code <noreply@anthropic.com>

Author: matteius

django_forms_workflows/admin.py

@@ -37,6 +37,7 @@
     ManagedFile,
     NotificationLog,
     NotificationRule,
+    PaymentRecord,
     PostSubmissionAction,
     PrefillSource,
     SharedOptionList,
@@ -702,6 +703,20 @@ class FormDefinitionAdmin(nested_admin.NestedModelAdmin):
                 ),
             },
         ),
+        (
+            "Payment",
+            {
+                "classes": ("collapse",),
+                "fields": (
+                    "payment_enabled",
+                    "payment_provider",
+                    ("payment_amount_type", "payment_fixed_amount"),
+                    "payment_amount_field",
+                    "payment_currency",
+                    "payment_description_template",
+                ),
+            },
+        ),
         (
             "Metadata",
             {
@@ -832,6 +847,13 @@ def clone_forms(self, request, queryset):
                         allow_withdrawal=form.allow_withdrawal,
                         allow_resubmit=form.allow_resubmit,
                         allow_batch_import=form.allow_batch_import,
+                        payment_enabled=form.payment_enabled,
+                        payment_provider=form.payment_provider,
+                        payment_amount_type=form.payment_amount_type,
+                        payment_fixed_amount=form.payment_fixed_amount,
+                        payment_amount_field=form.payment_amount_field,
+                        payment_currency=form.payment_currency,
+                        payment_description_template=form.payment_description_template,
                         created_by=request.user,
                     )
 
@@ -2053,6 +2075,26 @@ def has_change_permission(self, request, obj=None):
         return False
 
 
+class PaymentRecordInline(admin.TabularInline):
+    model = PaymentRecord
+    extra = 0
+    readonly_fields = (
+        "provider_name",
+        "transaction_id",
+        "amount",
+        "currency",
+        "status",
+        "error_message",
+        "created_at",
+        "completed_at",
+        "idempotency_key",
+    )
+    can_delete = False
+
+    def has_add_permission(self, request, obj=None):
+        return False
+
+
 @admin.register(FormSubmission)
 class FormSubmissionAdmin(admin.ModelAdmin):
     list_display = (
@@ -2074,7 +2116,7 @@ class FormSubmissionAdmin(admin.ModelAdmin):
     )
     raw_id_fields = ("submitter",)
     readonly_fields = ("created_at", "submitted_at", "completed_at")
-    inlines = [ChangeHistoryInline]
+    inlines = [PaymentRecordInline, ChangeHistoryInline]
 
 
 @admin.register(ApprovalTask)
@@ -2262,6 +2304,41 @@ def item_count(self, obj):
     item_count.short_description = "Options"
 
 
+@admin.register(PaymentRecord)
+class PaymentRecordAdmin(admin.ModelAdmin):
+    list_display = (
+        "transaction_id",
+        "submission",
+        "provider_name",
+        "amount",
+        "currency",
+        "status",
+        "created_at",
+        "completed_at",
+    )
+    list_filter = ("status", "provider_name", "currency")
+    search_fields = ("transaction_id", "submission__id", "idempotency_key")
+    readonly_fields = (
+        "submission",
+        "form_definition",
+        "provider_name",
+        "transaction_id",
+        "amount",
+        "currency",
+        "description",
+        "status",
+        "error_message",
+        "provider_data",
+        "created_at",
+        "updated_at",
+        "completed_at",
+        "idempotency_key",
+    )
+
+    def has_add_permission(self, request):
+        return False
+
+
 # --- File Upload Configuration Admin ---
 
 

django_forms_workflows/apps.py

@@ -23,3 +23,9 @@ def ready(self):
         from .callback_registry import load_from_settings
 
         load_from_settings()
+
+        # Auto-register bundled payment providers
+        from .payments import register_provider
+        from .payments.stripe_provider import StripePaymentProvider
+
+        register_provider("stripe", StripePaymentProvider)

django_forms_workflows/form_builder_views.py

@@ -254,11 +254,17 @@ def form_builder_view(request, form_id=None):
         "name"
     )
 
+    # Get available payment providers
+    from .payments import get_provider_choices
+
+    payment_provider_choices = get_provider_choices()
+
     context = {
         "form_definition": form_definition,
         "prefill_sources": prefill_sources,
         "shared_option_lists": shared_option_lists,
         "field_types": field_types_json,
+        "payment_provider_choices_json": json.dumps(payment_provider_choices),
         "is_new": form_id is None,
     }
 
@@ -328,6 +334,15 @@ def form_builder_load(request, form_id):
         else None,
         "max_submissions": form_definition.max_submissions,
         "one_per_user": form_definition.one_per_user,
+        "payment_enabled": form_definition.payment_enabled,
+        "payment_provider": form_definition.payment_provider,
+        "payment_amount_type": form_definition.payment_amount_type,
+        "payment_fixed_amount": str(form_definition.payment_fixed_amount)
+        if form_definition.payment_fixed_amount
+        else None,
+        "payment_amount_field": form_definition.payment_amount_field,
+        "payment_currency": form_definition.payment_currency,
+        "payment_description_template": form_definition.payment_description_template,
         "enable_captcha": form_definition.enable_captcha,
         "enable_multi_step": form_definition.enable_multi_step,
         "form_steps": form_definition.form_steps or [],
@@ -367,6 +382,13 @@ def form_builder_save(request):
         close_date = data.get("close_date") or None
         max_submissions = data.get("max_submissions") or None
         one_per_user = data.get("one_per_user", False)
+        payment_enabled = data.get("payment_enabled", False)
+        payment_provider = data.get("payment_provider", "")
+        payment_amount_type = data.get("payment_amount_type", "fixed")
+        payment_fixed_amount = data.get("payment_fixed_amount") or None
+        payment_amount_field = data.get("payment_amount_field", "")
+        payment_currency = data.get("payment_currency", "usd")
+        payment_description_template = data.get("payment_description_template", "")
         enable_captcha = data.get("enable_captcha", False)
         enable_multi_step = data.get("enable_multi_step", False)
         form_steps = data.get("form_steps", [])
@@ -403,6 +425,15 @@ def form_builder_save(request):
                 form_definition.close_date = close_date
                 form_definition.max_submissions = max_submissions
                 form_definition.one_per_user = one_per_user
+                form_definition.payment_enabled = payment_enabled
+                form_definition.payment_provider = payment_provider
+                form_definition.payment_amount_type = payment_amount_type
+                form_definition.payment_fixed_amount = payment_fixed_amount
+                form_definition.payment_amount_field = payment_amount_field
+                form_definition.payment_currency = payment_currency
+                form_definition.payment_description_template = (
+                    payment_description_template
+                )
                 form_definition.enable_captcha = enable_captcha
                 form_definition.enable_multi_step = enable_multi_step
                 form_definition.form_steps = form_steps
@@ -426,6 +457,13 @@ def form_builder_save(request):
                     close_date=close_date,
                     max_submissions=max_submissions,
                     one_per_user=one_per_user,
+                    payment_enabled=payment_enabled,
+                    payment_provider=payment_provider,
+                    payment_amount_type=payment_amount_type,
+                    payment_fixed_amount=payment_fixed_amount,
+                    payment_amount_field=payment_amount_field,
+                    payment_currency=payment_currency,
+                    payment_description_template=payment_description_template,
                     enable_captcha=enable_captcha,
                     enable_multi_step=enable_multi_step,
                     form_steps=form_steps,

django_forms_workflows/migrations/0085_add_payment_system.py

@@ -0,0 +1,170 @@
+# Generated by Django 5.2.7 on 2026-04-02 00:05
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("django_forms_workflows", "0084_add_shared_option_list"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="formdefinition",
+            name="payment_amount_field",
+            field=models.CharField(
+                blank=True,
+                help_text="field_name of a currency/decimal field for dynamic amounts.",
+                max_length=100,
+            ),
+        ),
+        migrations.AddField(
+            model_name="formdefinition",
+            name="payment_amount_type",
+            field=models.CharField(
+                blank=True,
+                choices=[("fixed", "Fixed Amount"), ("field", "From Form Field")],
+                default="fixed",
+                max_length=20,
+            ),
+        ),
+        migrations.AddField(
+            model_name="formdefinition",
+            name="payment_currency",
+            field=models.CharField(
+                blank=True,
+                default="usd",
+                help_text="ISO 4217 currency code (e.g., 'usd', 'cad').",
+                max_length=3,
+            ),
+        ),
+        migrations.AddField(
+            model_name="formdefinition",
+            name="payment_description_template",
+            field=models.CharField(
+                blank=True,
+                help_text="Charge description. Supports {field_name} tokens.",
+                max_length=500,
+            ),
+        ),
+        migrations.AddField(
+            model_name="formdefinition",
+            name="payment_enabled",
+            field=models.BooleanField(
+                default=False, help_text="Require payment for form submission."
+            ),
+        ),
+        migrations.AddField(
+            model_name="formdefinition",
+            name="payment_fixed_amount",
+            field=models.DecimalField(
+                blank=True,
+                decimal_places=2,
+                help_text="Fixed payment amount (when amount type is 'fixed').",
+                max_digits=10,
+                null=True,
+            ),
+        ),
+        migrations.AddField(
+            model_name="formdefinition",
+            name="payment_provider",
+            field=models.CharField(
+                blank=True,
+                help_text="Registered payment provider key (e.g., 'stripe').",
+                max_length=50,
+            ),
+        ),
+        migrations.AlterField(
+            model_name="formsubmission",
+            name="status",
+            field=models.CharField(
+                choices=[
+                    ("draft", "Draft"),
+                    ("pending_payment", "Pending Payment"),
+                    ("submitted", "Submitted"),
+                    ("pending_approval", "Pending Approval"),
+                    ("approved", "Approved"),
+                    ("rejected", "Rejected"),
+                    ("withdrawn", "Withdrawn"),
+                ],
+                default="draft",
+                max_length=20,
+            ),
+        ),
+        migrations.CreateModel(
+            name="PaymentRecord",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("provider_name", models.CharField(max_length=50)),
+                (
+                    "transaction_id",
+                    models.CharField(blank=True, db_index=True, max_length=255),
+                ),
+                ("amount", models.DecimalField(decimal_places=2, max_digits=10)),
+                ("currency", models.CharField(default="usd", max_length=3)),
+                ("description", models.CharField(blank=True, max_length=500)),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("pending", "Pending"),
+                            ("requires_action", "Requires Action"),
+                            ("processing", "Processing"),
+                            ("completed", "Completed"),
+                            ("failed", "Failed"),
+                            ("cancelled", "Cancelled"),
+                            ("refunded", "Refunded"),
+                        ],
+                        default="pending",
+                        max_length=20,
+                    ),
+                ),
+                ("error_message", models.TextField(blank=True)),
+                ("provider_data", models.JSONField(blank=True, null=True)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                ("completed_at", models.DateTimeField(blank=True, null=True)),
+                ("idempotency_key", models.CharField(max_length=255, unique=True)),
+                (
+                    "form_definition",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.PROTECT,
+                        related_name="payment_records",
+                        to="django_forms_workflows.formdefinition",
+                    ),
+                ),
+                (
+                    "submission",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="payment_records",
+                        to="django_forms_workflows.formsubmission",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Payment Record",
+                "verbose_name_plural": "Payment Records",
+                "ordering": ["-created_at"],
+                "indexes": [
+                    models.Index(
+                        fields=["submission", "status"],
+                        name="django_form_submiss_d8e9e5_idx",
+                    ),
+                    models.Index(
+                        fields=["transaction_id"], name="django_form_transac_44dbea_idx"
+                    ),
+                ],
+            },
+        ),
+    ]